Skip to content

Commit 3eb6c1f

Browse files
rbeyerrbeyer
committed
docs(CONTRIBUTING.rst): Added workflow/release matrix.
1 parent 0b0fa4b commit 3eb6c1f

File tree

1 file changed

+140
-0
lines changed

1 file changed

+140
-0
lines changed

‎CONTRIBUTING.rst‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,3 +194,143 @@ directly.
194194

195195
Committers are expected to follow this policy and continue to send
196196
pull requests, go through proper review, etc.
197+
198+
199+
Workflow and Deploying
200+
----------------------
201+
202+
The workflow concept we use in the pvl project is as follows.
203+
If you are familiar with Git workflows, it is mostly based on a
204+
Gitflow model, but there is not a separate *develop* branch from
205+
the *main* branch (at the moment, we don't need that much formalism),
206+
so *main* is the development branch.
207+
208+
The pvl library follows the `Semantic Versioning 2.0.0
209+
specification <https://semver.org>`_, such that released pvl
210+
version numbers follow this pattern: ``{major}.{minor}.{patch}``.
211+
212+
In this section, as a shorthand for ``{major}.{minor}.{patch}``,
213+
we will use *a.b.c*, but all actual versions in the repo will be
214+
numeric. When we talk about version *a.b.c*, consider those letters
215+
as immutable variables that hold integers, and ``a += 1 == b, c +=
216+
1 == d``, etc. So *a.b.c* is some starting state, which could
217+
represent *1.2.3*, then *a.b.d* would be *1.2.4* or *a.c.0* would
218+
be *1.3.0*, etc.
219+
220+
Here is an example workflow :
221+
222+
+------------------------------------------------+--------+-------+-----------+
223+
| Bugfix Workflow | Branch | Tests | Version |
224+
+================================================+========+=======+===========+
225+
| After the commit that releases a.b.c to main | main | pass | a.b.c |
226+
| it should have been tagged va.b.c | | | |
227+
+------------------------------------------------+--------+-------+-----------+
228+
| **A software bug is discovered.** |
229+
+------------------------------------------------+--------+-------+-----------+
230+
| Make a *hotfix* branch (could be an external | hotfix | | |
231+
| PR branch) | | | |
232+
+------------------------------------------------+ +-------+ |
233+
| First commit should be the 'failing tests' | | fail | |
234+
| commit. Craft tests to verify the failure | | | |
235+
| mode and commit the tests, without touching | | | |
236+
| the main code. This allows others to see | | | |
237+
| exactly what the problems are. | | | |
238+
+------------------------------------------------+ | | |
239+
| Make commits on *hotfix* to address issue | | | |
240+
+------------------------------------------------+ +-------+ |
241+
| Once tests pass, make a final commit, and it | | pass | |
242+
| is ready for merging! | | | |
243+
+------------------------------------------------+--------+-------+-----------+
244+
| External developers can now issue a pull request to get this merged into |
245+
| master. |
246+
| |
247+
| What follows is what internal developers do when a PR is received: |
248+
+------------------------------------------------+--------+-------+-----------+
249+
| Checkout the proposed *hotfix* branch and | hotfix | | |
250+
| verify: | | | |
251+
| | | | |
252+
| 1. Are there tests that exercise the bug? | | | |
253+
| 2. Does ``make lint`` pass? | | | |
254+
| 3. Does ``make test`` pass? | | | |
255+
| 4. Does ``make test-all`` pass? | | | |
256+
| 5. Is it based on master? | | | |
257+
| | | | |
258+
| Iterate with the submitter, if needed. | | | |
259+
+------------------------------------------------+--------+-------+-----------+
260+
| When satisfied with the above (no pushing until after the tag step): |
261+
+------------------------------------------------+--------+-------+-----------+
262+
| Starting state: ``git checkout master`` | main | pass | a.b.c |
263+
+------------------------------------------------+--------+ | |
264+
| ``git branch hotfix`` | hotfix | | |
265+
| | | | |
266+
| Checkout hotfix, may need to | | | |
267+
| ``git rebase master`` if master has advanced. | | | |
268+
+------------------------------------------------+ | +-----------+
269+
| Commit with bump2version:: | | | a.b.d-dev |
270+
| | | | |
271+
| bump2version patch | | | |
272+
+------------------------------------------------+ +-------+ |
273+
| Is there a suitable first `failing-tests` | | fail | |
274+
| commit? If not, decide how important it is. | | in | |
275+
| If it is important to have those failing tests | | the | |
276+
| as the first item in the commit history, then | | first | |
277+
| you'll have to do some commit surgery with | | commit| |
278+
| ``git rebase -i`` and other things to arrange | | | |
279+
| that. | | | |
280+
+------------------------------------------------+ +-------+ |
281+
| * If there are any new external developers: | | pass | |
282+
| add to ``AUTHORS.rst`` (if they haven't) | | | |
283+
| * Edit ``HISTORY.rst`` to describe what | | | |
284+
| happened by reviewing commit messages. | | | |
285+
| * If there are any commits in master since | | | |
286+
| the last release, include them in the | | | |
287+
| ``HISTORY.rst`` file, too. | | | |
288+
| * Otherwise check that everything is ready | | | |
289+
| to be merged back into master, and perform | | | |
290+
| a final pre-bump commit. | | | |
291+
+------------------------------------------------+ | | |
292+
| Tidy commits with ``git rebase -i master`` | | | |
293+
| so that the commit history looks like this | | | |
294+
| (most recent last): | | | |
295+
| | | | |
296+
| #. Found a bug, these tests show what's wrong | | | |
297+
| #. Bump version: a.b.c → a.b.d-dev | | | |
298+
| #. Fixed the bug by doing x, y, and z | | | |
299+
| | | | |
300+
| Additional commits are fine, but any final | | | |
301+
| ``HISTORY.rst`` or ``AUTHORS.rst`` changes | | | |
302+
| should probably be squashed into the last | | | |
303+
| commit. | | | |
304+
+------------------------------------------------+ | +-----------+
305+
| This wraps up this branch and readies it for | | | a.b.d |
306+
| merging with master:: | | | |
307+
| | | | |
308+
| bump2version release --tag | | | |
309+
| --tag-message | | | |
310+
| 'something descriptive' | | | |
311+
+------------------------------------------------+--------+ | |
312+
| apply to master:: | main | | |
313+
| | | | |
314+
| git checkout master | | | |
315+
| git merge hotfix | | | |
316+
+------------------------------------------------+ | | |
317+
| :: | | | |
318+
| | | | |
319+
| git push | | | |
320+
| git push --tags | | | |
321+
+------------------------------------------------+--------+-------+-----------+
322+
| The topic branch can now be deleted:: |
323+
| |
324+
| git branch -d hotfix |
325+
+-----------------------------------------------------------------------------+
326+
| Go to GitHub repo, ensure that all tests passed. |
327+
| |
328+
| If so, go to "Releases" and "Draft New Release" |
329+
| |
330+
| Give the most recent HISTORY.rst entry as the "description" of the Release. |
331+
| |
332+
| This should then trigger the upload to PyPI workflow. |
333+
+-----------------------------------------------------------------------------+
334+
| Once PyPI updates, conda-forge should notice and auto-PR an update. |
335+
+-----------------------------------------------------------------------------+
336+

0 commit comments

Comments
 (0)