| 1 |
Using GitHub |
| 2 |
============ |
| 3 |
|
| 4 |
GitHub contributions typically work by creating a fork of the project on your user account, making a branch on that fork to work on and then filing a pull request to upstream your code. This is how you would go about it. |
| 5 |
|
| 6 |
Forking |
| 7 |
------- |
| 8 |
|
| 9 |
Go to the `libMariaS3 GitHub page <https://github.com/mariadb-corporation/libmarias3>`_ and click the *Fork* button near the top. Once you have forked you can get a local copy of this fork to work on (where *user* is your username): |
| 10 |
|
| 11 |
.. code-block:: bash |
| 12 |
|
| 13 |
git clone https://github.com/user/libmarias3.git |
| 14 |
|
| 15 |
You then need to make your local clone aware of the upstream repository: |
| 16 |
|
| 17 |
.. code-block:: bash |
| 18 |
|
| 19 |
cd libmarias3 |
| 20 |
git remote add upstream https://github.com/mariadb-corporation/libmarias3.git |
| 21 |
|
| 22 |
Branch |
| 23 |
------ |
| 24 |
|
| 25 |
Before creating a branch to work on you should first make sure your local copy is up to date: |
| 26 |
|
| 27 |
.. code-block:: bash |
| 28 |
|
| 29 |
git checkout master |
| 30 |
git pull --ff-only upstream master |
| 31 |
git push |
| 32 |
|
| 33 |
You can then create a branch from master to work on: |
| 34 |
|
| 35 |
.. code-block:: bash |
| 36 |
|
| 37 |
git checkout -b a_new_feature |
| 38 |
|
| 39 |
Hack on code! |
| 40 |
------------- |
| 41 |
|
| 42 |
Hack away at your feature or bug. |
| 43 |
|
| 44 |
Test |
| 45 |
---- |
| 46 |
|
| 47 |
Once your code is ready the test suite should be run locally: |
| 48 |
|
| 49 |
.. code-block:: bash |
| 50 |
|
| 51 |
make |
| 52 |
make check |
| 53 |
|
| 54 |
If there are documentation changes you should install ``python-sphinx`` and try to build the HTML version to run a syntax check: |
| 55 |
|
| 56 |
.. code-block:: bash |
| 57 |
|
| 58 |
make html |
| 59 |
|
| 60 |
Commit and push |
| 61 |
--------------- |
| 62 |
|
| 63 |
If you have never contributed to GitHub before then you need to setup git so that it knows you for the commit message: |
| 64 |
|
| 65 |
.. code-block:: bash |
| 66 |
|
| 67 |
git config --global user.name "Real Name" |
| 68 |
git config --global user.email "[email protected]" |
| 69 |
|
| 70 |
Make sure you use `git add` to add any new files to the repository and then commit: |
| 71 |
|
| 72 |
.. code-block:: bash |
| 73 |
|
| 74 |
git commit -a |
| 75 |
|
| 76 |
Your editor will pop up to enter a commit messages above the comments. The first line should be no more than 50 characters and be a subject of the commit. The second line should be blank. The third line onwards can contain details and these should be no more than 72 characters each. |
| 77 |
|
| 78 |
If your commit fixes an issue you can add the following (for issue #93):: |
| 79 |
|
| 80 |
Fixes mariadb-corporation/libmarias3#93 |
| 81 |
|
| 82 |
Once all your commits are done a quick rebase may be needed to make sure your changes will merge OK with what is in master: |
| 83 |
|
| 84 |
.. code-block:: bash |
| 85 |
|
| 86 |
git fetch upstream |
| 87 |
git rebase -i upstream/master |
| 88 |
|
| 89 |
This should bring up a commit-style message in the editor with *pick* as the first word. Save this and the rebase will complete. If the rebase tells you there is a conflict you will need to locate the problem using ``git diff``, fix it and do: |
| 90 |
|
| 91 |
.. code-block:: bash |
| 92 |
|
| 93 |
git add <filename> |
| 94 |
git rebase --continue |
| 95 |
|
| 96 |
If things look like they are going wrong you can undo the rebase using the following and can get in touch with us: |
| 97 |
|
| 98 |
.. code-block:: bash |
| 99 |
|
| 100 |
git rebase --abort |
| 101 |
|
| 102 |
You should now be ready to push up to GitHub: |
| 103 |
|
| 104 |
.. code-block:: bash |
| 105 |
|
| 106 |
git push --set-upstream origin a_new_feature |
| 107 |
|
| 108 |
If you go to your repository on GitHub's website you will an option to file a *Pull Request*. Use this to submit a pull request upstream for your branch. |
| 109 |
|
| 110 |
Help |
| 111 |
---- |
| 112 |
|
| 113 |
If you get stuck at any point feel free to reach out to us by filing an issue on Github. |