From f792b1ad9da2709b932c093e7deee742934c5d46 Mon Sep 17 00:00:00 2001 From: Chichi Lalescu <clalesc1@jhu.edu> Date: Wed, 23 Dec 2015 22:33:43 +0100 Subject: [PATCH] add description of versioning guidelines --- README.rst | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ done.txt | 1 + todo.txt | 15 +++++++------- 3 files changed, 65 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index 78315b6e..4284a716 100644 --- a/README.rst +++ b/README.rst @@ -13,6 +13,14 @@ in the repository), and it is working as expected. Parameters and statistics are stored in HDF5 format, together with code information, so simulation data should be "future proof". +Users of this code are expected to either use `NavierStokes` objects +directly, or construct their own class that inherits this class. +The way I use it is to I inherit and add custom statistics as necessary; I +also have private C++ code that can get added and used when needed. +I plan on adding documentation on the procedure as when other people +show interest in using the code, or when time permits. + + Installation ------------ @@ -51,3 +59,52 @@ Comments compatibility should be kept since mayavi (well, vtk actually) only works on Python 2. + +=========== +Development +=========== + +`bfps` is using `git` for version tracking (see https://git-scm.com/ +for description). +The branching model described at +http://nvie.com/posts/a-successful-git-branching-model/ should be +adhered to as strictly as possible. + +The usable `VERSION` number will be constructed according to semantic +versioning rules (see http://semver.org/), `MAJOR.MINOR.PATCH`. +In principle, if you use `bfps` and you've created children of the +`NavierStokes` class, you should not need to rewrite your code unless +the `MAJOR` version changes. + +Versioning guidelines +--------------------- + +There are 2 main branches, `master` and `develop`. +`setup.py` will call `git` to read in the `VERSION`: it will get the +latest available tag. +If the active branch name contains either of the strings `develop`, +`feature` or `bugfix`, then the full output of `git describe --tags` +will be used; +otherwise, only the string before the dash (if a dash exists) will be +used. + +At the moment the following rules seem adequate. +Once I get feedback from someone who actually knows how to handle bigger +projects, these may change. + +1. New features are worked on in branches forked from `develop`, with + the branch name of the form `feature/bla`. + Feature branches are merged back into `develop` only after all tests + pass. +2. Whenever the `develop` branch is merged into `master`, the last + commit on the `develop` branch is tagged with `MAJOR.MINOR`. +3. Whenever a bug is discovered in version X.Y, a new branch called `vX.Y` + is forked from the corresponding `master` merge point. + A new bugfix branch is forked from `vX.Y`, the bug is fixed, and then + this bugfix branch is merged into all affected branches (this includes + `vX.Y`). + After merging, the respective merge points are tagged adequately (`vX.Y` + gets the tag X.Y.1). +4. Whenever a bug is discovered in version X.Y.Z, a bugfix branch is + forked from `vX.Y`, and then rule 3 is adapted accordingly. + diff --git a/done.txt b/done.txt index 11abcd19..78739201 100644 --- a/done.txt +++ b/done.txt @@ -1 +1,2 @@ x 2015-12-04 make code py3 compatible @python3 +x 2015-12-23 decide on versioning system +merge0 diff --git a/todo.txt b/todo.txt index f8738acc..71c2677e 100644 --- a/todo.txt +++ b/todo.txt @@ -1,13 +1,12 @@ -(B) FFTW interpolator doesn't need its own field @optimization +merge0 -(B) compute z polynomials only when needed @optimization +merge0 -(B) get rid of temporal interpolation @optimization +merge0 -(B) move get_grid coords to interpolator @optimization +merge0 +(B) FFTW interpolator doesn't need its own field @optimization +v1.0 +(B) compute z polynomials only when needed @optimization +v1.0 +(B) get rid of temporal interpolation @optimization +v1.0 +(B) move get_grid coords to interpolator @optimization +v1.0 (B) use less memory @optimization -(C) clean up machine_settings mess @design @documentation +merge1 +(C) clean up machine_settings mess @design @documentation +v2.0 (C) code overview @documentation -(C) decide on versioning system +merge0 -(C) move stat I/O to cpp lib @design @HDF5 +merge1 -(C) set up mechanism for adding in new PDEs @design +merge1 +alternate_algorithms +(C) move stat I/O to cpp lib @design @HDF5 +(C) set up mechanism for adding in new PDEs @design +v2.0 +alternate_algorithms (C) test involving hydrodynamic similarity @tests (C) use HDF5 io for fields @design @HDF5 +I/O (D) test anisotropic grids @tests -- GitLab