Skip to content

Commit a6be253

Browse files
gonukegonuke
committed
Overhaul of contributing to match current practices
1 parent 1a0589f commit a6be253

1 file changed

Lines changed: 86 additions & 74 deletions

File tree

‎CONTRIBUTING.rst‎

Lines changed: 86 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,14 @@ The Developer Workflow
66
General Notes
77
=============
88

9-
* The terminology we use is based on the `Integrator Workflow
10-
<http://en.wikipedia.org/wiki/Integrator_workflow>`_
11-
12-
* Use a branching workflow similar to the one described at
13-
http://progit.org/book/ch3-4.html.
9+
* We expect contributors to use a forking workflow `as described here
10+
<https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow>`_.
1411

1512
* Keep your own "main" branch in sync with the mainline
1613
repository's "main" branch. Specifically, do not push your
1714
own commits directly to your "main" branch.
1815

19-
* Any commit should *pass all tests* (see `Running Tests`_).
16+
* Any pull request should *pass all tests* (see `Running Tests`_).
2017

2118
* See the `An Example`_ section below for a full walk through
2219

@@ -86,93 +83,108 @@ An Example
8683
Introduction
8784
------------
8885

89-
As this type of workflow can be complicated to converts from SVN and very complicated
90-
for brand new programmers, an example is provided.
86+
As this type of workflow can be complicated, an example is provided.
9187

9288
For the sake of simplicity, let us assume that we want a single "sandbox" branch
9389
in which we would like to work, i.e. where we can store all of our work that may not
9490
yet pass tests or even compile, but where we also want to save our progress. Let us
95-
call this branch "Work". So, when all is said and done, in our fork there will be
96-
three branches: "Master", "Develop", and "Work".
91+
call this branch ``work``. So, when all is said and done, in our fork there will be
92+
two branches: ``main`` and ``work``
9793

9894
Acquiring Cyclus and Workflow
9995
-----------------------------
10096

10197
We begin with a fork of the mainline Cyclus repository. After initially forking
102-
the repo, we will have the main branch in your fork.
98+
the repo, we will have the ``main`` branch in your fork.
10399

104100
Acquiring a Fork of the Cyclus Repository
105101
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
106102

107-
A fork is *your* copy of Cyclus. Github offers an excellent
108-
`tutorial <http://help.github.com/fork-a-repo/>`_ on how to set one up. The rest of this
109-
example assumes you have set up the "upstream" repository as ``cyclus/core``. Note that git
110-
refers to your fork as "origin".
103+
A fork is *your* copy of Cyclus. Github offers an excellent `tutorial
104+
<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo>`_
105+
on how to create a fork and then setup your local development evnironment with
106+
remote connections to both the ``upstream`` repository at ``cyclus/cyclus`` and
107+
your fork of this repository referred to as ``origin``.
111108

112-
First, let's make our "work" branch:
109+
First, let's make our ``work`` branch. Assuming that you are in the ``cyclus`` directory:
113110
::
114-
.../cyclus_dir/$ git branch work
115-
.../cyclus_dir/$ git push origin work
111+
$ git branch work
112+
$ git push origin work
116113

117-
We now have the following situation: there exists the mainline copy of the main
118-
branch, there exists your fork's copy of the main and working branches,
119-
*AND* there exists your *local* copy of the main and working branches. It is
120-
important now to note that you may wish to work from home or the office. If you keep your
121-
fork's branches up to date (i.e., "push" your changes before you leave), only your *local*
122-
copies of your branches may be different when you next sit down at the other location.
114+
We now have the following situation: there exists the mainline copy of the ``main``
115+
branch, there exists your fork's copy of the ``main`` and ``work`` branches,
116+
*AND* there exists your *local* copy of the ``main`` and ``work`` branches.
123117

124-
Workflow: The Beginning
125-
^^^^^^^^^^^^^^^^^^^^^^^
118+
Workflow
119+
^^^^^^^^
126120

127121
Now, for the workflow! This is by no means the only way to perform this type of
128-
workflow, but I assume that you wish to handle conflicts as often as possible
129-
(so as to keep their total number small). Let us imagine that you have been at
130-
work, finished, and successfully pushed your changes to your *Origin*
131-
repository. You are now at home and want to continue working a bit. To begin,
132-
let's update our *home's local branches*::
133-
134-
.../cyclus_dir/$ git checkout main
135-
.../cyclus_dir/$ git pull upstream main
136-
.../cyclus_dir/$ git push origin main
137-
138-
.../cyclus_dir/$ git checkout work
139-
.../cyclus_dir/$ git pull origin work
140-
.../cyclus_dir/$ git rebase main
141-
.../cyclus_dir/$ git push origin work
142-
143-
Perhaps a little explanation is required. We first want to make sure that this new local copy of
144-
the main branch is up-to-date with respect to the remote origin's branch and remote upstream's
145-
branch. If there was a change from the remote upstream's branch, we want to push that to origin.
146-
We then follow the same process to update the work branch, except:
147-
148-
#. we don't need to worry about the *upstream* repo because it doesn't have a work branch, and
149-
#. we want to incorporate any changes which may have been introduced in the main branch update.
150-
151-
Workflow: The End
152-
^^^^^^^^^^^^^^^^^
153-
154-
As time passes, you make some changes to files, and you commit those changes (to your *local work
155-
branch*). Eventually (hopefully) you come to a stopping point where you have finished your project
156-
on your work branch *AND* it compiles *AND* it runs input files correctly *AND* it passes all tests!
157-
Perhaps you have found Nirvana. In any case, you've performed the final commit to your work branch,
158-
so it's time to make a pull request online and wait for our main friends to
159-
review and accept it.
160-
161-
Sometimes, your pull request will be held by the reviewer until further changes
162-
are made to appease the reviewer's concerns. This may be frustrating, but please
163-
act rationally, discuss the issues on the GitHub space made for your pull
164-
request, consult the `style guide
165-
<http://cyclus.github.com/devdoc/style_guide.html>`_, email the developer
166-
listhost for further advice, and make changes to your topic branch accordingly.
167-
The pull request will be updated with those changes when you push them to your
168-
fork. When you think your request is ready for another review, you can reopen
169-
the review yourself with the button made available to you.
170-
171-
See also
172-
--------
173-
174-
A good description of a git workflow with good graphics is available at
175-
http://nvie.com/posts/a-successful-git-branching-model/
122+
workflow, but we assume that you wish to handle conflicts as often as possible
123+
(so as to keep their total number small).
124+
125+
As time passes, you make some changes to files, and you commit those changes (to
126+
your *local ``work`` branch*). Eventually (hopefully) you come to a stopping
127+
point where you have finished your project on your ``work`` branch *AND* it
128+
compiles *AND* it runs input files correctly *AND* it passes all tests! Perhaps
129+
you have found Nirvana.
130+
131+
Over this time, it is possible that the ``main`` branch into which you are
132+
proposing your pull request has advanced with other changes. In order to make
133+
sure your ``work`` branch remains up to date, you will want to periodically
134+
rebase your ``work`` branch onto the ``upstream/main`` branch. This will
135+
process will reapply all of the changes you have made on top of the most
136+
up-to-date version of the ``upstream/main`` branch. Even if you have not been
137+
doing this regularly, you'll want to do it before you initiate a pull request.
138+
::
139+
140+
$ git checkout main
141+
$ git pull upstream main
142+
$ git checkout work
143+
$ git rebase main
144+
$ git push origin work
145+
146+
Note: you may need to force the push of the rebased ``work`` branch to your fork.
147+
148+
In any case, you've performed the final commit to your ``work`` branch, so it's
149+
time to make a pull request online and wait for our main friends to review and
150+
accept it.
151+
152+
Sometimes, your pull request will be held by the reviewer until
153+
further changes are made to appease the reviewer's concerns. This may be
154+
frustrating, but please act rationally, discuss the issues on the GitHub space
155+
made for your pull request, consult the `style guide
156+
<http://cyclus.github.com/devdoc/style_guide.html>`_, reach out on `slack
157+
<https://cyclus-nuclear.slack.com>`_ for further advice, and make changes to
158+
your ``work`` branch accordingly. The pull request will be updated with those
159+
changes when you push them to your fork. When you think your request is ready
160+
for another review, you can reopen the review yourself with the button made
161+
available to you.
162+
163+
Synchronizing across multiple computers
164+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
165+
You may wish to work on different computers over time, sometime on your laptop
166+
and other times on a desktop at the office. If you keep your fork's branches up
167+
to date (i.e., "push" your changes before you leave), only your *local* copies
168+
of your branches may be different when you next sit down at the other location.
169+
170+
Let us imagine that you have been at the office, finished, and successfully
171+
pushed your changes to your ``origin`` repository. You are now at home and want
172+
to continue working a bit on your laptop. To begin, let's update our *laptop's
173+
local branches*
174+
::
175+
$ git checkout work
176+
$ git pull origin work
177+
178+
This may also be a good time to ensure your ``work`` branch is up-to-date with the
179+
``upstream/main`` branch
180+
::
181+
182+
$ git chekout main
183+
$ git pull upstream main
184+
$ git checkout work
185+
$ git rebase main
186+
$ git push origin work
187+
176188

177189
Releases
178190
========

0 commit comments

Comments
 (0)