Skip to content
This repository was archived by the owner on Apr 18, 2018. It is now read-only.

Commit 5f63391

Browse files
edoddridgejahn
authored andcommitted
add quickstart guide to manual for code contribs
The instructions in `howtocontribute.txt` have been included in the manual in the quick start section for code contributions.
1 parent 72aeedf commit 5f63391

File tree

1 file changed

+57
-0
lines changed

1 file changed

+57
-0
lines changed

doc/contributing.rst

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,63 @@ To contribute to the source code of the model you will need to fork the reposito
3030

3131
Quickstart Guide
3232
----------------
33+
You will need a GitHub account, but that's pretty much it!
34+
35+
1: Fork the project and create a local clone (copy)
36+
37+
You can fork by clicking the button, and create a clone either also by using the button, or in a terminal:
38+
``git clone https://github.com/user_name/MITgcm66h.git``
39+
(substitute your own user name on github)
40+
41+
move into the new directory:
42+
``cd MITgcm66h``
43+
44+
Finally, we need to set up a remote that points to the original project:
45+
``git remote add upstream https://github.com/altMITgcm/MITgcm66h.git``
46+
47+
This means that we have two "remotes" of the project, one pointing to your space (origin), and one pointing to the original (upstream). You can read and write into your "origin" version, but not into the "upstream" version.
48+
49+
2: Doing stuff! This usually comes in two flavours; Fixing bugs or adding a feature. Here we will assume we are fixing a bug and branch from the master, but if adding a new feature branching from develop is usually the way it works.
50+
51+
To fix this "bug" we check out the master branch, and make sure we're up to date.
52+
``git checkout master``
53+
``git pull upstream master && git push origin master``
54+
55+
Next make a new branch. Naming it something useful helps.
56+
``git checkout -b bugfix/contributingHowTo``
57+
58+
Do the work! Be sure to include useful and detailed commit messages.
59+
To do this you should:
60+
61+
- edit the relevant file(s)
62+
- use ``git add FILENAME`` to stage the file(s) ready for a commit command
63+
- use ``git commit`` to commit the files
64+
- type a succint (<70 character) summary of what the commit did
65+
- leave a blank line and type a longer description of why the action in this commit was appropriate
66+
- it is good practice to link with issues using the syntax ``#ISSUE_NUMBER`` in one or both of the above.
67+
68+
3: Now we push our branch into the origin remote.
69+
70+
``git push -u origin bugfix/contributingHowTo``
71+
72+
4: Then create a pull request (PR). In a browser, go to the fork of the project that you made. There is a button for "Compare and Pull" in your recent branches. Click the button! Now you can add a nice and succinct description of what you've done and flag up any issues.
73+
74+
75+
5: Review by the maintainers!
76+
77+
78+
79+
To sum up from https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project/
80+
81+
The fundamentals are:
82+
83+
#. Fork the project & clone locally.
84+
#. Create an upstream remote and sync your local copy before you branch.
85+
#. Branch for each separate piece of work.
86+
#. Do the work, write good commit messages, and read the guidelines in the manual.
87+
#. Push to your origin repository.
88+
#. Create a new PR in GitHub.
89+
#. Respond to any code review feedback.
3390

3491

3592

0 commit comments

Comments
 (0)