From cf956e5b5a2a301f65b0f402d44d022dd7da6b6e Mon Sep 17 00:00:00 2001 From: Nicola Nye Date: Fri, 24 Jun 2016 13:10:52 +1000 Subject: [PATCH 1/2] [Docs] Source repository has been moved out of Phabricator and onto GitHub. * Development processes have changed (no longer using Arcanist for patch management) * Repository URLs have changed. * Bug reporting has changed (Bugzilla and Maniphest will be migrated into a single location: GitHub issues) --- docsrc/conf.py | 6 +- docsrc/contribute.rst | 13 - docsrc/feedback-bugs.rst | 4 +- docsrc/feedback-meetings.rst | 4 +- docsrc/imap/developer.rst | 10 - docsrc/imap/developer/configure-fails.rst | 21 -- docsrc/imap/developer/developer-testing.rst | 45 +-- docsrc/imap/developer/docker.rst | 271 ------------------ docsrc/imap/developer/documentation.rst | 52 +--- docsrc/imap/developer/github-guide.rst | 96 +++++++ docsrc/imap/developer/installguide.rst | 42 +-- docsrc/imap/developer/make-check-fails.rst | 21 -- docsrc/imap/developer/make-fails.rst | 21 -- docsrc/imap/developer/overview.rst | 7 +- docsrc/imap/developer/pre-configure-fails.rst | 21 -- docsrc/imap/developer/process.rst | 50 +--- docsrc/imap/features/namespaces.rst | 4 +- docsrc/imap/installation/diy.rst | 19 +- .../imap/release-notes/3.0/x/3.0.0-beta3.rst | 3 + 19 files changed, 144 insertions(+), 566 deletions(-) delete mode 100644 docsrc/imap/developer/configure-fails.rst delete mode 100644 docsrc/imap/developer/docker.rst create mode 100644 docsrc/imap/developer/github-guide.rst delete mode 100644 docsrc/imap/developer/make-check-fails.rst delete mode 100644 docsrc/imap/developer/make-fails.rst delete mode 100644 docsrc/imap/developer/pre-configure-fails.rst diff --git a/docsrc/conf.py b/docsrc/conf.py index 1eb9d14dbd..422f3db8d0 100644 --- a/docsrc/conf.py +++ b/docsrc/conf.py @@ -1132,7 +1132,7 @@ """ rst_prolog += """ -.. |git_cyrus_imapd_url| replace:: https://git.cyrus.foundation/diffusion/I/cyrus-imapd.git +.. |git_cyrus_imapd_url| replace:: https://github.com/cyrusimap/cyrus-imapd.git """ # The version in which compatibility support for RFC 2086 (the 'c' and @@ -1183,14 +1183,14 @@ #You are looking at documentation that is maintained by interval. - #Please see https://docs.cyrus.foundation/ for better maintained + #Please see https://www.cyrusimap.org/ for better maintained #documentation. #""" # Use this as :task:`18` extlinks = { 'rfc':('http://tools.ietf.org/html/rfc%s', 'RFC '), - 'task':('https://git.cyrus.foundation/T%s', 'Task #'), + 'task':('https://github.com/cyrusimap/cyrus-imapd/issues/%s', 'Task #'), } # Change this to whatever your output root is diff --git a/docsrc/contribute.rst b/docsrc/contribute.rst index 1362356ad7..eef73fd37d 100644 --- a/docsrc/contribute.rst +++ b/docsrc/contribute.rst @@ -4,19 +4,6 @@ Contributor Guide =================== - -Contribute Financially -====================== - -If you wish to provide financial support to the Cyrus Project, send a check payable to Carnegie Mellon University to:: - - Project Cyrus - Computing Services - Carnegie Mellon University - 5000 Forbes Ave - Pittsburgh, PA 15213 - USA - Website Content Contributions ============================= diff --git a/docsrc/feedback-bugs.rst b/docsrc/feedback-bugs.rst index 2aa8907241..6a0f6a6b4b 100644 --- a/docsrc/feedback-bugs.rst +++ b/docsrc/feedback-bugs.rst @@ -1,8 +1,8 @@ Reporting Bugs ============== -Bug reports can be logged in our `Bugzilla issue tracker `__. Please bear in mind registration is required. -When reporting a bug, please prepare to provide the following information; +Bug reports can be sent to us through our :ref:`mailing list ` or logged in our `GitHub issue tracker `__. Bear in mind registration is required. +When reporting a bug, please provide the following information; * Your platform, and if applicable, your distribution and the distribution version. * The exact version of Cyrus IMAP or SASL you are using. diff --git a/docsrc/feedback-meetings.rst b/docsrc/feedback-meetings.rst index 5152a68d0d..90dddf415e 100644 --- a/docsrc/feedback-meetings.rst +++ b/docsrc/feedback-meetings.rst @@ -4,7 +4,7 @@ Online Meetings Join us online! -Regular contributors catch up online twice weekly, both as a status checkpoint and to make sure we're all alive! +Regular contributors catch up online weekly, both as a status checkpoint and to make sure we're all alive! -Meetings are currently held at **Monday 11am GMT** and **Thursday midday GMT** via `Google Hangouts `_. +Meetings are currently held at **Monday 11am GMT** via `Google Hangouts `_. It's worth checking on `IRC ` to confirm the time and URL if nobody else seems to be online. diff --git a/docsrc/imap/developer.rst b/docsrc/imap/developer.rst index df0b7d3192..6a9aeb8246 100644 --- a/docsrc/imap/developer.rst +++ b/docsrc/imap/developer.rst @@ -31,15 +31,5 @@ Resources :maxdepth: 1 developer/libraries - developer/docker -Continuous Integration -====================== -.. toctree:: - :maxdepth: 1 - - developer/pre-configure-fails - developer/configure-fails - developer/make-fails - developer/make-check-fails diff --git a/docsrc/imap/developer/configure-fails.rst b/docsrc/imap/developer/configure-fails.rst deleted file mode 100644 index f52ffb11e2..0000000000 --- a/docsrc/imap/developer/configure-fails.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _imap-developer-configure-fails: - -================================================ -Error Message: Step ``configure`` fails on (...) -================================================ - -When `Dr. Jenkins`_ raises a concern with a commit, (...) - -To reproduce the issue, see :ref:`imap-developer-docker-images` to fire -up a Docker container of your own, with an interactive shell. - -Normally, the script ``/entrypoint.sh`` is executed, so you can -reproduce this as follows: - -.. parsed-literal:: - - $ :command:`COMMIT= /entrypoint.sh` - -It *should* output the commands it issues. - -.. _Dr. Jenkins: https://git.cyrus.foundation/p/jenkins/ diff --git a/docsrc/imap/developer/developer-testing.rst b/docsrc/imap/developer/developer-testing.rst index 350e4fbc22..2c3f6950f0 100644 --- a/docsrc/imap/developer/developer-testing.rst +++ b/docsrc/imap/developer/developer-testing.rst @@ -22,12 +22,9 @@ Persian Empire. So that's kinda cool. Install and configure Cassandane -------------------------------- -1. Clone the Cassandane repository (you can get the URL from the Diffusion app within Phabricator) +1. Clone the Cassandane repository - * If you are a member of `IMAP Committers`_, use: ``git clone ssh://git@git.cyrus.foundation/diffusion/C/cassandane.git`` - * If you aren't (yet), use ``git clone https://git.cyrus.foundation/diffusion/C/cassandane.git`` - -.. _IMAP Committers: https://git.cyrus.foundation/tag/imap_committers/ + * ``git clone https://github.com/cyrusimap/cassandane.git`` 2. Install dependencies @@ -42,38 +39,6 @@ Install and configure Cassandane libmime-types-perl libdatetime-format-iso8601-perl libcal-dav-perl \ libclone-perl -There are a number of Perl modules required that aren't already packages in the standard repository. A few aren't in CPAN yet and should be installed from github. - -.. code-block:: bash - - git clone https://github.com/brong/Net-DAVTalk/ - cd Net-DAVTalk - perl Makefile.PL - make - sudo make install - cd .. - - git clone https://github.com/brong/Net-CardDAVTalk/ - cd Net-CardDAVTalk - perl Makefile.PL - make - sudo make install - cd .. - - git clone https://github.com/brong/Net-CalDAVTalk/ - cd Net-CalDAVTalk - perl Makefile.PL - make - sudo make install - cd .. - - git clone https://github.com/brong/Mail-JMAPTalk/ - cd Mail-JMAPTalk - perl Makefile.PL - make - sudo make install - cd .. - The quickest option for the rest is installing via CPAN, but you could build packages using dh-make-perl if that is preferred. .. code-block:: bash @@ -86,7 +51,11 @@ The quickest option for the rest is installing via CPAN, but you could build pac sudo cpan -i Mail::IMAPTalk sudo cpan -i List::Pairwise sudo cpan -i Convert::Base64 - + sudo cpan -i Net::DAVTalk + sudo cpan -i Net::CardDAVTalk + sudo cpan -i Net::CalDAVTalk + sudo cpan -i Mail::JMAPTalk + 3. Install Cassandane .. code-block:: bash diff --git a/docsrc/imap/developer/docker.rst b/docsrc/imap/developer/docker.rst deleted file mode 100644 index 1bb5d4eecb..0000000000 --- a/docsrc/imap/developer/docker.rst +++ /dev/null @@ -1,271 +0,0 @@ -.. _imap-developer-docker-images: - -============= -Docker Images -============= - -The Cyrus IMAP uses Docker images for testing builds and performing unit -tests for, at the time of this writing, 13 (releases of) Linux -distributions. - -The images are configured to start running tests automatically (i.e. -they have an *entrypoint*). To get an interactive shell, see -:ref:`imap-developer-docker-images-interactive-shell`. - -The results of the tests are posted to our `Phabricator`_ instance as -comments to commits, or raise a concern (which in turn becomes an -`Audit`_ request). - -When `Dr. Jenkins`_ raises a concern with a commit, she intends to raise -awareness over builds failing. - -The current state of the tree is compared to the last state of the tree -using the *parent* of the *current* commit. - -* If a step in *current* fails, but the *parent* also fails, - `Dr. Jenkins`_ will only leave a comment -- with one exception; - - If :ref:`imap-developer-docker-images-make-relaxed` fails, checking - the parent is irrelevant, and a concern is raised -- triggering an - audit. - -* If a step in *current* fails, but it does not fail in the *parent*, - it is likely the commit broke the build (or that the `Dr. Jenkins` - script does not work). This raises a concern too. - -Quick Notes -=========== - -* If the environment variables ``PHAB_CERT`` and ``PHAB_USER`` are - specified, Arcanist is installed and configured. - - This enables you to run through a debugging session on a specific - platform, interacting with, for example, `Differential`_ or - `Diffusion`_ at https://git.cyrus.foundation. - - You can obtain your certificate, which is a very long string, from - Phabricator's `Conduit`_. - -* To apply a Differential revision regardless, specify the - ``DIFFERENTIAL`` environment variable. - - .. NOTE:: - - Do not specify the ``D`` in the variable, just the number. - -* The images come with **vim** pre-installed and pre-configured to: - - #. Remember the last position in a file you've opened, - - #. Employ syntax highlighting, - - #. Apply the current latest indentation policy for Cyrus IMAP. - -* In an interactive shell, ``PROMPT_COMMAND`` is set to have the - terminal window you have open reflect the name of the image you are - running and running multiple of them is not just a bunch of windows - titled with container IDs. - -Environment Variables -===================== - -``COMMIT`` - - More commonly referred to as a *git ref*, the ``COMMIT`` environment - variable is used to issue a ``git checkout ${COMMIT}`` with. - - **Examples:** - - Run against ``HEAD`` of the ``cyrus-imapd-2.5`` branch: - - .. parsed-literal:: - - $ :command:`docker run -it -e "COMMIT=cyrus-imapd-2.5" \\ - cyrusimapd/maipo` - - .. IMPORTANT:: - - The images and scripts do not currently support Cyrus IMAP - versions prior to 2.5.0. - -``CONFIGURE_OPTS`` - - Use the options specified to run ``./configure``, rather then the - default configure options. - - **Examples:** - - #. Test with a yet unknown configure option added by a - `Differential`_ revision (don't forget to also set the - ``DIFFERENTIAL`` environment variable): - - .. parsed-literal:: - - $ :command:`docker run -it -e "CONFIGURE_OPTS=--enable-ceph" \\ - cyrusimapd/maipo` - - #. Test an option that is otherwise known to fail: - - .. parsed-literal:: - - $ :command:`docker run -it -e "CONFIGURE_OPTS=--with-openssl=no" \\ - cyrusimapd/wheezy` - -``DIFFERENTIAL`` - - Before running anything, apply the `Differential`_ revision - specified. - - .. NOTE:: - - Only specify the number, not the ``D`` prefix. - - **Examples:** - - Test a `Differential`_ revision: - - .. parsed-literal:: - - $ :command:`docker run -it -e "DIFFERENTIAL=9" \\ - cyrusimapd/santiago` - -``PHAB_CERT`` - -``PHAB_USER`` - -Future Environment Variables ----------------------------- - -``BUILD_ID`` - - We intend to run the Docker containers as part of the - `Harbormaster`_ and `DryDock`_ applications in `Phabricator`_, for - the purposes of continuous integration -- rather than comment on - commits individually. - -``TICKET`` - - Report to a `Maniphest`_ ticket rather than the `Diffusion`_ commit. - -Running the Tests Yourself -========================== - -.. parsed-literal:: - - $ :command:`docker run -ti cyrusimapd/heisenbug` - -.. NOTE:: - - Aside from specifying a ``PHAB_CERT`` environment variable, this is - how tests are run when they result in a comment or concern on a - commit. - -.. _imap-developer-docker-images-interactive-shell: - -Getting an Interactive Shell -============================ - -.. parsed-literal:: - - $ :command:`docker run -ti --entrypoint="/bin/bash" cyrusimapd/heisenbug -s` - -This will give you an interactive shell. - -The images are configured with an entry point of :file:`/entrypoint.sh`, -so maybe you want to execute that. - -Functions for Your Convenience -============================== - -Functions are pulled from :file:`/entrypoint.sh` so you can -:command:`source /functions.sh` which gives you the following commands: - -``_make_relaxed`` - - This command configures the build with relaxed ``CFLAGS``, as - opposed to ``-g -Wall -Wextra -Werror``. - -``_make_strict`` - - This command configures the build with strict ``CFLAGS``, turning - all warnings to errors: ``-g -Wall -Wextra -Werror``. - -Build Process Steps -=================== - -``./configure`` (maintainer mode) ---------------------------------- - -If the ``CONFIGURE_OPTS`` environment variable has been specified, the -following commands are run automatically: - -.. parsed-literal:: - - $ :command:`./configure --enable-maintainer-mode` - $ :command:`make \\ - imap/rfc822_header.c \\ - imap/rfc822_header.h` - -These *should* not fail, but if they do, it's probably your fault. See -:ref:`imap-developer-pre-configure-fails`. - -.. NOTE:: - - If ``CONFIGURE_OPTS`` is not specified, then - :ref:`imap-developer-docker-images-configure-for-real` takes care of - specifying the required ``--enable-maintainer-mode`` option. - -.. _imap-developer-docker-images-configure-for-real: - -``./configure`` (for real) --------------------------- - -Configure is run for real, using either the defined ``CONFIGURE_OPTS`` -or a default of (at the time of this writing): - -.. parsed-literal:: - - ./configure \\ - --enable-autocreate \\ - --enable-coverage \\ - --enable-gssapi \\ - --enable-http \\ - --enable-idled \\ - --enable-maintainer-mode \\ - --enable-murder \\ - --enable-nntp \\ - --enable-replication \\ - --enable-unit-tests \\ - --with-ldap=/usr - -If the second run of ``./configure`` fails for whatever reason, the -script checks out the *parent* of the *current* commit and tries again. - -.. _imap-developer-docker-images-make-relaxed: - -``make`` (relaxed) ------------------- - -The first run of ``make`` is *relaxed*, meaning that ``CFLAGS`` are -default. - -``make`` (strict) ------------------ - -The second run of ``make`` is *strict*, meaning that ``CFLAGS`` are -default. - -``make check`` --------------- - -Execute the CUnit tests in ``cunit.``. - -.. _Audit: https://git.cyrus.foundation/audit/ -.. _Conduit: https://git.cyrus.foundation/settings/panel/conduit/ -.. _Differential: https://git.cyrus.foundation/differential/ -.. _Diffusion: https://git.cyrus.foundation/diffusion/ -.. _Dr. Jenkins: https://git.cyrus.foundation/p/jenkins/ -.. _DryDock: https://git.cyrus.foundation/drydock/ -.. _Harbormaster: https://git.cyrus.foundation/harbormaster/ -.. _Maniphest: https://git.cyrus.foundation/maniphest/ -.. _Phabricator: https://git.cyrus.foundation/ diff --git a/docsrc/imap/developer/documentation.rst b/docsrc/imap/developer/documentation.rst index 6c20f62f3e..0064086238 100644 --- a/docsrc/imap/developer/documentation.rst +++ b/docsrc/imap/developer/documentation.rst @@ -11,7 +11,7 @@ Our documentation for the website is held under git source control, the same as Our helpfile source uses Sphinx_ and `Restructured Text`_. -While editing the documentation can take place in any text editor, you'll need tools to fetch the source, generate man pages and html for testing and tools to submit your updates via Arcanist. +While editing the documentation can take place in any text editor, you'll need tools to fetch the source, generate man pages and html for testing. Documentation Tools =================== @@ -50,67 +50,31 @@ For interaction with the repositories * git * git-stuff -To support Arcanist - -* php5-cli -* php5-curl - Checking the files ================== -For a full-fledged test generating Sphinx output, run:: +For a full-fledged test generating Sphinx output, from the checkout directory run:: make clean init man html -from the checkout directory and look at the results. This generates the manpages and the html files. +This generates the manpages and the html files. Look at the results in ``build``. Run make with no arguments for a list of available output targets. Submitting updates ================== -Using Phabricator/Arcanist +Using GitHub pull requests -------------------------- -This assumes you aren't a member of the `Documentation Committers`_ group on Phabricator_ and thus are subject to a mandatory review step by the `Documentation Reviewers`_ group. - -1. Take ownership of a Maniphest_ task (or create a new task). You'll need a Phabricator_ account to do this. -2. Clone the source -3. Make a new branch (either via ``git checkout -b`` or using ``arc feature``) -4. Code code test test test code code test test test. -5. Use git to commit your changes. -6. When you are ready to submit your changes to a Differential - - * use: ``arc diff`` to commit to origin/master, or ``arc diff `` to commit to an alternate branch. - * Various checks take place, after which you are requested to provide some details about your proposed changes. Please fill out in detail as this will help speedy review and acceptance of your change. - * For changes to Documentation, the reviewers section should be set to #Documentation_Reviewers. - * It is important to note that arc does not allow you to specify, as part of the commit message, whether or not your diff depends on any other existing diffs. - -7. Wait for review (a quick note to the mailing list can speed this along) -8. Once approved, it'll be merged into the master. +We operate on the GitHub fork/pull model. We'd love to have your pull request come through! -Reviewing Code -############## - -Reviewing Differential revisions is a job for volunteer members of the `Documentation Reviewers`_ projects. Only those people that have direct commit access are eligible to become a reviewer (because otherwise the process doesn't work). - -When a reviewer initially starts review, they execute ``arc patch D5``. This gets Arcanist to checkout a branch arcpatch-D5 (or a variant of that name, such as arcpatch-D5_1 if arcpatch-D5 already existed) and the changeset for the revision is applied. - -The reviewer examines and comments on the related Differential revision. If the change is to be accepted, the reviewer must set the Differential to 'Accepted'. This allows the diff to be landed. - -| For changes to be applied to master: ``arc land arcpatch-D5`` -| For changes to apply on another branch: ``arc land arcpatch-D5 --onto cyrus-imapd-2.4`` +If you're new to GitHub or the fork/pull model, we have a :ref:`Quick GitHub guide ` to get you going. Patches through the mailing list -------------------------------- -If you're not planning on regularly submitting changes, you can just send your patch through to the mailing list and one of the regular maintainers will see about incorporating it. - -.. _Documentation Committers: https://git.cyrus.foundation/tag/documentation_committers/ -.. _IMAP Reviewers: https://git.cyrus.foundation/tag/imap_reviewers/ -.. _SASL Reviewers: https://git.cyrus.foundation/tag/sasl_reviewers/ -.. _Documentation Reviewers: https://git.cyrus.foundation/tag/documentation_reviewers/ -.. _Maniphest: https://git.cyrus.foundation/maniphest/ -.. _Phabricator: https://git.cyrus.foundation/ +If you're not planning on regularly submitting changes, you can just send your patch through to the :ref:`mailing list ` and one of the regular maintainers will incorporate it. + .. _Sphinx: http://sphinx-doc.org .. _Restructured Text: http://docutils.sourceforge.net/rst.html diff --git a/docsrc/imap/developer/github-guide.rst b/docsrc/imap/developer/github-guide.rst new file mode 100644 index 0000000000..72cb8eb724 --- /dev/null +++ b/docsrc/imap/developer/github-guide.rst @@ -0,0 +1,96 @@ +.. _github-guide: + +============ +GitHub guide +============ + +A walkthrough for using GitHub_ with a view to providing updates (source or documentation or testing) to the `Cyrus repository`_. + +1. :ref:`Create a GitHub account ` +2. :ref:`Add your ssh key ` +3. :ref:`Fork the repository ` to make a copy of the code for you to apply changes to. +4. :ref:`Issue a pull request ` to request that your changes are incorporated back into the master codebase. + +This guide assumes you are familiar with the workings of `Git `_ for source control. + +.. _github-guide-account: + +1. Create a GitHub account +-------------------------- + +Go to GitHub_ and sign up for an account. You only need the free plan to contribute to Cyrus. + +Their `help pages `_ have more information +on filling out your profile and setting up two-factor authentication for additional security. + +.. _github-guide-sshkey: + +2. Add your ssh key +------------------- + +It's worth adding a ssh key to your account, so you're not having to input your password every time you access the repository. + +If you don't have an ssh key already (and `here's how to check `_), +you can `generate a new key `_. Once you have a key, +`add it to GitHub `_ and +`test it out `_. + + +.. _github-guide-fork: + +3. Fork the repository +---------------------- + +Whether you're contributing to `Cyrus `_ (source, or documentation), +contributing to tests with `Cassandane `_ or into helping out with `SASL `_ or +any of the other `Cyrus component projects `_, use the Fork button to make a copy of the repository into your own GitHub work space. + +GitHub has more information on `how to fork a repository `_. + +Once you have a forked copy, you can clone it into your working area on your computer. + +:: + + git clone https://github.com/YOUR-USERNAME/REPOSITORY-NAME.git + +You will then want to set your local copy to get its changes from the original repository, so it stays in sync. Use ``git remote -v`` to show the current origins of your clone which will currently be your fork. + +:: + + git remote -v + origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch) + origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push) + +We want to set that instead to point to the primary original upstream repository. + +:: + + git remote add upstream https://github.com/cyrusimap/REPOSITORY-NAME.git + +Now we can check to see that the upstream is set: + +:: + + git remote -v + origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch) + origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push) + upstream https://github.com/cyrusimap/ORIGINAL_REPOSITORY.git (fetch) + upstream https://github.com/cyrusimap/ORIGINAL_REPOSITORY.git (push) + +We recommend you create a topic branch and make your changes (don't forget to :ref:`test! `). Using a topic branch means you can keep your master +source in sync without affecting your changes. It also means that if your patch undergoes further revisions before inclusion, you +can easily do so. + +.. _github-guide-pull: + +4. Issue a pull request +----------------------- + +When your changes are done, you `issue a pull request `_. +This is done by logging into the GitHub interface, swapping to your branch, then selecting New Pull Request. + +When submitting the pull request, note if there's a particular filed bug your patch addresses. The Cyrus Team +will review your pull request and make sure it gets integrated! + +.. _GitHub: https://github.com +.. _Cyrus repository: https://github.com/cyrusimap/ diff --git a/docsrc/imap/developer/installguide.rst b/docsrc/imap/developer/installguide.rst index ef9e3a8c1c..67fb9476ae 100644 --- a/docsrc/imap/developer/installguide.rst +++ b/docsrc/imap/developer/installguide.rst @@ -16,21 +16,7 @@ Fetching Cyrus You'll need access to the cyrus-imapd git repository. -1. You'll need a public key. If you don't already have a `~/.ssh/id_rsa.pub`, then create one with `ssh-keygen(1)`. - * Use the GitHub guide, following `steps 1-3`_ - -2. Login to Phabricator_ - * Go to the `SSH Keys settings panel`_. - * Click **Upload public key** - * Paste the contents of your ``~/.ssh/id_rsa.pub`` (n.b. NOT ``~/.ssh/id_rsa``!) into the public key box. - * Give it a descriptive name and click **Upload** - -3. Install git if you don't already have it: - * ``sudo apt-get install git`` - -4. Clone the cyrus-imapd repository (you can get this URL from the Diffusion app within Phabricator): - * If you are a member of `IMAP Committers`_, use ``git clone ssh://git@git.cyrus.foundation/diffusion/I/cyrus-imapd.git`` - * If you aren't (yet), use ``git clone https://git.cyrus.foundation/diffusion/I/cyrus-imapd.git`` +Follow our :ref:`Guide to GitHub ` for details on how to access the repository, fork it, clone it, and branch it. Setting up dependencies ----------------------- @@ -47,11 +33,6 @@ Setting up dependencies * ``sudo pip install python-sphinx`` * ``sudo cpan install Pod::POM::View::Restructured`` -.. _steps 1-3: https://help.github.com/articles/generating-ssh-keys/ -.. _Phabricator: https://git.cyrus.foundation/ -.. _SSH Keys settings panel: https://git.cyrus.foundation/settings/panel/ssh/ -.. _IMAP Committers: https://git.cyrus.foundation/tag/imap_committers/ - Compile Cyrus --------------- @@ -86,27 +67,6 @@ It may be of use to also add ``--std=gnu99`` to the ``CFLAGS``. That generates You may see warnings regarding libical v2.0 being recommended to support certain functionality. Currently libical v1.0.1 is sufficient, unless you need/want RSCALE (non-gregorian recurrences), VPOLL (consensus scheduling), or VAVAILABILITY (specifying availability over time) functionality. If v2 is required, it will need to be installed from `github `_. -Arcanist -========= - -Installing Arcanist --------------------- - -Arcanist is a tool for managing workflow (code review, etc), which sits between git and Phabricator. - -.. note:: - - Conrad (@conradk) says: "Installing arcanist on Ubuntu was apparently as easy as ``sudo apt-get install arcanist``. But, the folks over at arcanist say: "clone the code from GitHub." - -1. `Install Arcanist`_ -2. Set up Arcanist - * cd in to any of the GIT repositories (so that the ./.arcconfig file included in those has the upper hand for the next step) - * Link your local arc to Phabricator: ``arc install-certificate`` - -3. Get familiar with the :ref:`Arcanist workflow ` - -.. _Install Arcanist: https://secure.phabricator.com/book/phabricator/article/arcanist/#installing-arcanist - Setting up syslog ================= diff --git a/docsrc/imap/developer/make-check-fails.rst b/docsrc/imap/developer/make-check-fails.rst deleted file mode 100644 index 3b78cefed6..0000000000 --- a/docsrc/imap/developer/make-check-fails.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _imap-developer-make-check-fails: - -================================================= -Error Message: Step ``make-check`` fails on (...) -================================================= - -When `Dr. Jenkins`_ raises a concern with a commit, (...) - -To reproduce the issue, see :ref:`imap-developer-docker-images` to fire -up a Docker container of your own, with an interactive shell. - -Normally, the script ``/entrypoint.sh`` is executed, so you can -reproduce this as follows: - -.. parsed-literal:: - - $ :command:`COMMIT= /entrypoint.sh` - -It *should* output the commands it issues. - -.. _Dr. Jenkins: https://git.cyrus.foundation/p/jenkins/ diff --git a/docsrc/imap/developer/make-fails.rst b/docsrc/imap/developer/make-fails.rst deleted file mode 100644 index 1028be29c0..0000000000 --- a/docsrc/imap/developer/make-fails.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _imap-developer-make-fails: - -=========================================== -Error Message: Step ``make`` fails on (...) -=========================================== - -When `Dr. Jenkins`_ raises a concern with a commit, (...) - -To reproduce the issue, see :ref:`imap-developer-docker-images` to fire -up a Docker container of your own, with an interactive shell. - -Normally, the script ``/entrypoint.sh`` is executed, so you can -reproduce this as follows: - -.. parsed-literal:: - - $ :command:`COMMIT= /entrypoint.sh` - -It *should* output the commands it issues. - -.. _Dr. Jenkins: https://git.cyrus.foundation/p/jenkins/ diff --git a/docsrc/imap/developer/overview.rst b/docsrc/imap/developer/overview.rst index 66b7aaab12..b24e7e6ef0 100644 --- a/docsrc/imap/developer/overview.rst +++ b/docsrc/imap/developer/overview.rst @@ -46,11 +46,10 @@ IMAPTest Development hub --------------- -Phabricator - We use Phabricator_ for our collaboration and change tracking. Diffusion provides repository browsing, Differential provides code review, Maniphest provides bug tracking. Arcanist_ provides a command-line interface to Phabricator. +GitHub + We use GitHub for our collaboration and change tracking. Check out our :ref:`development process ` for a guide on how to contribute your changes to the community. -.. _Arcanist: https://secure.phabricator.com/book/phabricator/article/arcanist/ -.. _Phabricator: https://git.cyrus.foundation + diff --git a/docsrc/imap/developer/pre-configure-fails.rst b/docsrc/imap/developer/pre-configure-fails.rst deleted file mode 100644 index be288f663a..0000000000 --- a/docsrc/imap/developer/pre-configure-fails.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _imap-developer-pre-configure-fails: - -==================================================== -Error Message: Step ``pre-configure`` fails on (...) -==================================================== - -When `Dr. Jenkins`_ raises a concern with a commit, (...) - -To reproduce the issue, see :ref:`imap-developer-docker-images` to fire -up a Docker container of your own, with an interactive shell. - -Normally, the script ``/entrypoint.sh`` is executed, so you can -reproduce this as follows: - -.. parsed-literal:: - - $ :command:`COMMIT= /entrypoint.sh` - -It *should* output the commands it issues. - -.. _Dr. Jenkins: https://git.cyrus.foundation/p/jenkins/ diff --git a/docsrc/imap/developer/process.rst b/docsrc/imap/developer/process.rst index 5cee644e4d..52bc1cd59d 100644 --- a/docsrc/imap/developer/process.rst +++ b/docsrc/imap/developer/process.rst @@ -29,50 +29,30 @@ Found a bug? Got an enhancement? Great! Something to consider before you leap in with a new feature: this is an open source project. If your change isn't a basic part of what is already planned, will you be around to support it? Can you justify why it's in the best interests of the project to have your change included? We'd love to talk it through with you: contact us via the :ref:`mailing lists `. -Using Phabricator/Arcanist --------------------------- +Using GitHub +------------ -This assumes you aren't a member of the `IMAP Committers`_ group on Phabricator_ and thus are subject to a mandatory review step by the `IMAP Reviewers`_ group. +First, check out our :ref:`Guide to GitHub `, which covers: -1. Take ownership of a Maniphest_ task (or create a new task). You'll need a Phabricator_ account to do this. -2. Clone the source -3. Make a new branch (either via ``git checkout -b`` or using ``arc feature``) -4. Code code test test test code code test test test. -5. Use git to commit your changes. -6. When you are ready to submit your changes to a Differential - * use: ``arc diff`` to commit to origin/master, or ``arc diff `` to commit to an alternate branch. - * Various checks take place, after which you are requested to provide some details about your proposed changes. Please fill out in detail as this will help speedy review and acceptance of your change. - * For changes to IMAP, the reviewers section should be set to #IMAP_Reviewers, - * For changes to SASL, the reviewers section should be set to #SASL_Reviewers, and - * For changes to Documentation, the reviewers section should be set to... you guessed it... #Documentation_Reviewers. - * It is important to note that arc does not allow you to specify, as part of the commit message, whether or not your diff depends on any other existing diffs. +1. Create a GitHub account +2. Fork the repository +3. Clone the fork. +4. Branch the clone. -7. Wait for review (a quick note to the mailing list can speed this along) -8. Once approved, it'll be merged into the master. +From there, you: -Reviewing Code -############## +1. Take ownership of a GitHub issue (or create a new one to cover what you're planning to do). +2. Code code :ref:`test test test ` code code test test test. +3. Use git to commit your changes. +4. Issue a :ref:`pull request ` on GitHub +5. Wait for review (a quick note to the mailing list can speed this along) +6. Once approved, it'll be merged into the master. -Reviewing Differential revisions is a job for volunteer members of the `IMAP Reviewers`_, `SASL Reviewers`_ and/or `Documentation Reviewers`_ projects. Only those people that have direct commit access are eligible to become a reviewer (because otherwise the process doesn't work). - -When a reviewer initially starts review, they execute ``arc patch D5``. This gets Arcanist to checkout a branch arcpatch-D5 (or a variant of that name, such as arcpatch-D5_1 if arcpatch-D5 already existed) and the changeset for the revision is applied. - -The reviewer examines and comments on the related Differential revision. If the change is to be accepted, the reviewer must set the Differential to 'Accepted'. This allows the diff to be landed. - -| For changes to be applied to master: ``arc land arcpatch-D5`` -| For changes to apply on another branch: ``arc land arcpatch-D5 --onto cyrus-imapd-2.4`` Patches through the mailing list -------------------------------- If you're not planning on regularly submitting changes, you can just send your patch through to the mailing list and one of the regular maintainers will see about incorporating it. -.. _IMAP Committers: https://git.cyrus.foundation/tag/imap_committers/ -.. _IMAP Reviewers: https://git.cyrus.foundation/tag/imap_reviewers/ -.. _SASL Reviewers: https://git.cyrus.foundation/tag/sasl_reviewers/ -.. _Documentation Reviewers: https://git.cyrus.foundation/tag/documentation_reviewers/ -.. _Maniphest: https://git.cyrus.foundation/maniphest/ -.. _Phabricator: https://git.cyrus.foundation/ - Useful Developer Information ============================ @@ -83,6 +63,6 @@ Community Participation Join us! The project is only as good as the sum of its people. We all work together, despite the tyranny of distance and timezones. -Meetings are currently held online at **Monday 11am GMT** and **Thursday midday GMT** via `Google Hangouts `_. Not sure what time that is for you? Try the `meeting planner `_. +Meetings are currently :ref:`held online ` via Google Hangouts. Not sure what time that is for you? Try the `meeting planner `_. There's also :ref:`IRC and mailing lists `. diff --git a/docsrc/imap/features/namespaces.rst b/docsrc/imap/features/namespaces.rst index 737fe1ae5e..0e5bd940c3 100644 --- a/docsrc/imap/features/namespaces.rst +++ b/docsrc/imap/features/namespaces.rst @@ -390,8 +390,8 @@ Examples of shared folders could include: .. rubric:: Shared mail folders for mailing list traffic -* ``lists/cyrus.foundation/announce@example.org`` -* ``lists/cyrus.foundation/devel@example.org`` +* ``lists/cyrus.imap/announce@example.org`` +* ``lists/cyrus.imap/devel@example.org`` .. rubric:: Shared mail folders for common email addresses diff --git a/docsrc/imap/installation/diy.rst b/docsrc/imap/installation/diy.rst index 361275cc56..2b4ff4a785 100644 --- a/docsrc/imap/installation/diy.rst +++ b/docsrc/imap/installation/diy.rst @@ -17,23 +17,8 @@ the GIT repository's branches, or a tarball of a released version. From GIT ======== -Clone the GIT repository: - -.. parsed-literal:: - - $ :command:`git clone https://git.cyrus.foundation/diffusion/I/cyrus-imapd.git` - -Check out the desired branch or revision: - -.. parsed-literal:: - - $ :command:`git branch -la` - * master - (...snip...) - remotes/origin/cyrus-imapd-2.3 - remotes/origin/cyrus-imapd-2.4 - remotes/origin/cyrus-imapd-2.5 - $ :command:`git checkout` *$branch* +Read our :ref:`Guide to GitHub ` for details on how to +access our GitHub repository, and fork/clone the source. Continue with :ref:`imap-installation-diy-build-dependencies`. diff --git a/docsrc/imap/release-notes/3.0/x/3.0.0-beta3.rst b/docsrc/imap/release-notes/3.0/x/3.0.0-beta3.rst index 109c52e80c..c42ee461fa 100644 --- a/docsrc/imap/release-notes/3.0/x/3.0.0-beta3.rst +++ b/docsrc/imap/release-notes/3.0/x/3.0.0-beta3.rst @@ -25,6 +25,9 @@ Download via FTP: Major changes since the 2.5.x series ==================================== +* The source repository has moved to :ref:`GitHub `, Bugzilla and Phabricator + have been deprecated and their issue lists imported into GitHub. + * Support added for FastMail-style conversations (threaded messages). (See the ``conversations`` options in :ref:`imapd.conf `) From 268fe9ecd771a491652e4117fdd0c363808a553f Mon Sep 17 00:00:00 2001 From: Nicola Nye Date: Fri, 24 Jun 2016 14:01:03 +1000 Subject: [PATCH 2/2] [Docs] :task: (Phab) vs :issue: (GitHub) Revert :task: so it continues to point to Phabricator, but create new :issue: link for items now stored in GitHub issue tracker. --- docsrc/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docsrc/conf.py b/docsrc/conf.py index 422f3db8d0..200fb28bca 100644 --- a/docsrc/conf.py +++ b/docsrc/conf.py @@ -1190,7 +1190,8 @@ # Use this as :task:`18` extlinks = { 'rfc':('http://tools.ietf.org/html/rfc%s', 'RFC '), - 'task':('https://github.com/cyrusimap/cyrus-imapd/issues/%s', 'Task #'), + 'task':('https://git.cyrus.foundation/T%s', 'Task #'), + 'issue':('https://github.com/cyrusimap/cyrus-imapd/issues/%s', 'Issue #'), } # Change this to whatever your output root is