Skip to content

Coding Github_Cycle

Jump to bottom
EricBoix edited this page May 4, 2017 · 1 revision

Refrain from cloning the master: fork it instead

If you intend to contribute to any of the (Github) git repositories of the MUTS project (e.g. MEPP V2) it is strongly advised to refrain from cloning the master. Master is for integration, not development. Instead, the recommended workflow goes like:

  1. start with a fork of the concerned repository
  2. work on your fork (by first cloning it and then pushing to it)
  3. create a Pull Request (PR)
  4. improve your branch until the associated Travis CI tests (Linux gcc and clang) is OK (within the Pull Request tab, assert that the colored dot on the right of your PR is green)
  5. ask the "well known" Windows (currently Vincent Vidal and Martial Tola) and Mac OSX (currently Martial Tola) testing persons to manually test your branch,
  6. kindly request a benevolent "integration czar" to realize the merge with the master or request for changes

Note that the Windows test if often much more changeling than the OSX test but your mileage may vary. Also note that volunteers for becoming a Windoze/OSX testing person are welcomed.

If you inadvertently forgot to fork and started with cloning the master (e.g. MEPP V2, you should:

  • isolate your wishful changes
  • still realize the above described forking procedure
  • back port the changes you operated on your original master clone to your newly created fork

When not respecting the above workflow, the benevolent "integration czar" will escalate the enforcement process: frowning upon, chastising, punishment, severe punishment, cyanide, banning (only for survivors of previous stage :-)

Limit the CI rebuilds to really useful repository updates

Because the git repository is hooked up with a CI (Continuous Integration) tool (Travis) each commit triggers a rebuild. In order to avoid useless rebuilds (which will delay the useful ones), it is key to inhibit Travis rebuilds when committing non functionnal changes (e.g. doxygen or mardown based documentation). This is even more important when commiting often... In order to do so, simply embed a [ci skip] string anywhere in you commit message.

Submitting a Pull Request (PR)

When creating a PR, start the discussion with the following template:

 - [ ] Unit-test of your feature (ctest)
 - [ ] Doxygen documentation of the code completed (classes, methods, types, members...)
 - [ ] No build warnings raised (Travis, Appveyor)
 - [ ] All continuous integration tests pass (Travis, Appveyor)
 - [ ] Doxygen builds without new warnings
 - [ ] Coding Style(https://github.com/MEPP-team/VCity/wiki/Coding-Style) respected
 - [ ] Changes.md updated

Checkbox might have an N/A content (in addition to being empty or have an x).

Optionnal entries that you can add (nice to have):

  • User guide provided (Doxygen module page added or updated)
  • Design notes provided (as Doxygen module page?)
  • New entry in the ChangeLog.md added.

Note: links to Coding Style, Changes.md...

Pull Request (PR) acceptance policy

A given Pull Request (PR) is handled over to a PR validator that will evaluate the submission which the following criteria:

  • all the items (refer above) of the PR submission template must be checked
  • the number of warnings (prior to the PR and after the PR) shall never increase (refer to list of known and unavoidable)

The PR submitter/validator exchanges will be written on github's PR submission interface. It is nevertheless always encouraged, whenever if possible, to first exchange through informal conversations/discussions prior to leaving some written traces of the work to be done (in the form of short concrete items).

In order to avoid any possible conflict of interest, and for a given PR, the submitter and the validator shall not be the same person.

Versioning process

Version number incrementation and the associated tagging process (described below) happens in the following conditions

  • every couple of weeks (the classic duration of a sprint the version sub-minor is incremented,
  • every couple of months (e.g. each semester) the version minor is incremented.

Notes:

  • for the time being the major will be kept to be zero (the code is not yet perfectly mature).
  • the version number can be obtained on the command line
    • after software installation: launch 3DUSE-config binary
    • when in the building tree: ctest -R TEST_PRINT_CONFIG -V

Evaluation of the pertinence for making a new version/release is evaluated during the weekly meeting and this task is attributed to the versioning-person in charge of following the versioning process

  • As recommended, place yourself in your forked working repository.
  • Upgrade the version numbers (for the sake of simplicity/clarity of the versioning process you should limit yourself to the two following changes) within:
    • the main CMakeLists.txt by changing the values of the PRJ_VERSION_MAJOR, PRJ_VERSION_MINOR and PRJ_VERSION_PATCHvariables.
    • dialogAbout.ui (part of the QT interface)
  • Commit and push those changes to your origin repository (i.e. your forked repository on github as opposed to your local repository on your desktop computer). Take note of the SHA1 for this push (e.g. d5304fb5c8e for version 0.4.0). In the following we will call VERSION_SHA1 this SHA1.
  • Submit an associated PR (e.g. the PR for version 0.4.0). Have this PR accepted and merged. Once your PC accepted you should be able to view your VERSION_SHA1 within the lists of commits of the master. For example for version 0.4.0 here is the VERSION_SHA1 (d5304fb5c8e) that you should distinguish from the SHA1 of the merge of your commit.
  • From your local repository (the one on your desktop), proceed with the tagging process at the git level
    • git remote -v command describes the situation in which you should now be, which should be similar to
      origin        https://github.com/<yourGithubLogin>/VCity.git (fetch)
  origin        https://github.com/<yourGithubLogin>/VCity.git (push)
  upstream https://github.com/MEPP-team/VCity.git (fetch)
  upstream	https://github.com/MEPP-team/VCity.git (push)
    • git log command will enable you to make sure that your VERSION_SHA1 is indeed present in the log list (it should be the top entry if you didn't do push other commits in between)
    • git tag -a <version_number> VERSION_SHA1 command tags the version on your local repository (in our example case this gives git tag -a v0.4.0 d5304fb5c8e): provide some message when asked (for example use the version number as message).
    • git push origin --tags command pushes the new tag to your forked repository. Note that tags don't get "pushed" with other commits and you do need to push tags separately. You should now see this new tag:
      • with the git ls-remote --tags on the command line or
      • on the release entry on your forked repository on github (releases appears on the right side of the commit button). For example here it is for version 0.4.0.
    • git push upstream --tagseventually pushes the tag on the master repository which you should be able to assert:
      • git ls-remote --tags https://github.com/MEPP-team/VCity.git on the command line
      • on the releases page of the original project on github (e.g. for version 0.4.0)
  • Don't forget to celebrate and to keep the hotline open ;-)
Clone this wiki locally