| 1 |
.. _github-guide: |
| 2 |
|
| 3 |
============ |
| 4 |
GitHub guide |
| 5 |
============ |
| 6 |
|
| 7 |
A walkthrough for using GitHub_ with a view to providing updates (source or documentation or testing) to the `Cyrus repository`_. |
| 8 |
|
| 9 |
1. :ref:`Create a GitHub account <github-guide-account>` |
| 10 |
2. :ref:`Add your ssh key <github-guide-sshkey>` |
| 11 |
3. :ref:`Fork the repository <github-guide-fork>` to make a copy of the code for you to apply changes to. |
| 12 |
4. :ref:`Issue a pull request <github-guide-pull>` to request that your changes are incorporated back into the master codebase. |
| 13 |
|
| 14 |
This guide assumes you are familiar with the workings of `Git <https://help.github.com/articles/set-up-git/>`_ for source control. |
| 15 |
|
| 16 |
.. _github-guide-account: |
| 17 |
|
| 18 |
1. Create a GitHub account |
| 19 |
-------------------------- |
| 20 |
|
| 21 |
Go to GitHub_ and sign up for an account. You only need the free plan to contribute to Cyrus. |
| 22 |
|
| 23 |
Their `help pages <https://help.github.com/articles/signing-up-for-a-new-github-account/>`_ have more information |
| 24 |
on filling out your profile and setting up two-factor authentication for additional security. |
| 25 |
|
| 26 |
.. _github-guide-sshkey: |
| 27 |
|
| 28 |
2. Add your ssh key |
| 29 |
------------------- |
| 30 |
|
| 31 |
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. |
| 32 |
|
| 33 |
If you don't have an ssh key already (and `here's how to check <https://help.github.com/articles/checking-for-existing-ssh-keys/>`_), |
| 34 |
you can `generate a new key <https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/>`_. Once you have a key, |
| 35 |
`add it to GitHub <https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/>`_ and |
| 36 |
`test it out <https://help.github.com/articles/testing-your-ssh-connection/>`_. |
| 37 |
|
| 38 |
|
| 39 |
.. _github-guide-fork: |
| 40 |
|
| 41 |
3. Fork the repository |
| 42 |
---------------------- |
| 43 |
|
| 44 |
Whether you're contributing to `Cyrus <https://github.com/cyrusimap/cyrus-imapd>`_ (source, or documentation), |
| 45 |
or into helping out with `SASL <https://github.com/cyrusimap/cyrus-sasl>`_ or |
| 46 |
any of the other `Cyrus component projects <https://github.com/cyrusimap>`_, use the Fork button to make a copy of the repository into your own GitHub work space. |
| 47 |
|
| 48 |
GitHub has more information on `how to fork a repository <https://help.github.com/articles/fork-a-repo/>`_. |
| 49 |
|
| 50 |
Once you have a forked copy, you can clone it into your working area on your computer. |
| 51 |
|
| 52 |
:: |
| 53 |
|
| 54 |
git clone https://github.com/YOUR-USERNAME/REPOSITORY-NAME.git |
| 55 |
|
| 56 |
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. |
| 57 |
|
| 58 |
:: |
| 59 |
|
| 60 |
$ git remote -v |
| 61 |
origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch) |
| 62 |
origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push) |
| 63 |
|
| 64 |
We want to set that instead to point to the primary original upstream repository. |
| 65 |
|
| 66 |
:: |
| 67 |
|
| 68 |
git remote add upstream https://github.com/cyrusimap/REPOSITORY-NAME.git |
| 69 |
|
| 70 |
Now we can check to see that the upstream is set: |
| 71 |
|
| 72 |
:: |
| 73 |
|
| 74 |
$ git remote -v |
| 75 |
origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch) |
| 76 |
origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push) |
| 77 |
upstream https://github.com/cyrusimap/ORIGINAL_REPOSITORY.git (fetch) |
| 78 |
upstream https://github.com/cyrusimap/ORIGINAL_REPOSITORY.git (push) |
| 79 |
|
| 80 |
We recommend you create a topic branch and make your changes (don't forget to :ref:`test! <developer-testing>`). Using a topic branch means you can keep your master |
| 81 |
source in sync without affecting your changes. It also means that if your patch undergoes further revisions before inclusion, you |
| 82 |
can easily do so. |
| 83 |
|
| 84 |
.. _github-guide-pull: |
| 85 |
|
| 86 |
4. Issue a pull request |
| 87 |
----------------------- |
| 88 |
|
| 89 |
When your changes are done, you `issue a pull request <https://help.github.com/articles/using-pull-requests/>`_. |
| 90 |
This is done by logging into the GitHub interface, swapping to your branch, then selecting New Pull Request. |
| 91 |
|
| 92 |
When submitting the pull request, note if there's a particular filed bug your patch addresses. The Cyrus Team |
| 93 |
will review your pull request and make sure it gets integrated! |
| 94 |
|
| 95 |
.. _GitHub: https://github.com |
| 96 |
.. _Cyrus repository: https://github.com/cyrusimap/ |