
GitHub guide
************

A walkthrough for using GitHub with a view to providing updates
(source or documentation or testing) to the Cyrus repository.

1. Create a GitHub account

2. Add your ssh key

3. Fork the repository to make a copy of the code for you to apply
   changes to.

4. 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.


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.


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.


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 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.


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!
