From 8671f8a607e8dfff1e9a973c2fcbcc081701cb9f Mon Sep 17 00:00:00 2001 From: ecasellas <eric.casellas@inrae.fr> Date: Thu, 27 Jan 2022 12:10:31 +0100 Subject: [PATCH] add doc for contributions practices --- Contributing.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 Contributing.md diff --git a/Contributing.md b/Contributing.md new file mode 100644 index 0000000..aa72b87 --- /dev/null +++ b/Contributing.md @@ -0,0 +1,158 @@ +# Working with source code + +The gtnash source code is hosted on a GitLab server (https://forgemia.inra.fr/game-theory-tools-group), and is made of several Git repositories. +They can be cloned with read and/or write acces depending on your granted +* gtnash python package : https://forgemia.inra.fr/game-theory-tools-group/gtnash-git.git +* experiments using gtnash : https://forgemia.inra.fr/game-theory-tools-group/gtnash-xp.git + +Before using Git for the first time, configure your Git user name and email address using the following rules: +* Write you name with only first letter capitalized, e.g. John Doe (not John DOE) +* If you have several email adresses, use the email adress related to the gtnash project (usually your work email address) + +```bash +git config --global user.name "John Doe" +git config --global user.email "jdoe@foobar.org" +``` + +As the gtnash source code management is based on Git, knowing Git basics is recommended (clone, commit, branch, fetch, merge, remote, push, ...). Some Git resources are listed at the bottom of this page, and could be a good entry point for beginners. + +## Branching model + +The branching model used for the gtnash developments relies on a single long term branch: the `main` branch, and many short term branches: the features branches. +* The `main` branch contains the source code in a ready-production state : compiles and builds perfectly, all tests run successfully. +* The features branches are used for development of single features and bug fixes, then are merged in the `main` branch. + +The reference `main` branch can only be updated by the integration manager(s). It is public with read-only access for contributing developers. +The features branches are for developers and each branch supports the work in progress of a single new feature or a single bugfix: +* A feature branch should be named using a shot definition of the work (i.e. fix-wrong-data-id), and should be prefixed by the ticket number if any (i.e. t147-fix-wrong-data-id) +* When created, the source code must come from the `main` branch +* During the branch life, the source code should be updated from the `main` branch updates +* Once completed, they are merged in the `main` branch by integration manager(s). +* A feature branch must not be deleted until it is merged in the `main` branch + +## Workflow + +### Overview + +* The `main` branch is hosted on the [reference Git repository on GitLab](https://forgemia.inra.fr/game-theory-tools-group/gtnash-git.git). +* The feature branches are hosted on developers repositories. These developers repositories must be public with read-only access to integration manager(s). +* For contributing to the gtnash project, it is recommended for developers to have an account on GitLab (https://forgemia.inra.fr) in order to host their own public repositories and use the fork system provided by this service. However, other hosting is possible so far as it provides read-only access to integration manager(s) + +### Practical example + +In this example, the the developer username is "\<USERNAME\>", and he uses the GitLab forking and hosting facilities for his public repository. The example feature to develop is a fix for the gtnash python package that will be integrated when it will be fully developed. + +#### On the developer's side + + + +**Prerequisite**: Prepare your developer repository (should be done only once) +* Fork the reference gtnash repository into your own public repository Go on the [gtnash source code repository on GitLab](https://forgemia.inra.fr/game-theory-tools-group/gtnash-git), and click on the Fork button (top right of the page) +Note that the Fork button performs a copy of the gtnash repository into the developer's public repository and do not keep repositories in sync. It is the responsability of the developer to maintain his repositories up-to-date (see below). +* Clone your public repository in your private local repository (https://forgemia.inra.fr/help/user/profile/personal_access_tokens.md) +```bash +git clone https://oauth2:<TOKEN>@forgemia.inra.fr/<USERNAME>/gtnash-git.git +``` +* Add the reference repository as a read-only upstream, and name it upstream +```bash +git remote add upstream https://forgemia.inra.fr/game-theory-tools-group/gtnash-git.git +``` +* Update your local repository from the reference repository +```bash +git checkout main +git fetch upstream +git merge upstream/main +``` +* Once updated, it is recommended to push your freshly updated private local repository to your public repository +```bash +git checkout main +git push origin main +``` +* Create your local branch for new feature, named `fix-dummy` in the examples below +```bash +git checkout -b fix-dummy main +``` +* Do your work, commit locally (following the practices for commits). You can also push to your public repository regularly. This can be done through your IDE (i.e. Eclipse) or using the command line. +For commiting your work: +```bash +git commit -m "the message" +``` +* For pushing your work to your public repository: +```bash +git checkout main +git fetch upstream +git merge upstream/main +git checkout fix-dummy +git rebase main +git push origin fix-dummy +``` +* Once your feature completed and rebased on top of the current `main` branch of the reference repository, submit a merge request to the integration manager. +Go to your `fix-dummy` branch and use the "Create merge request" button. + + + +* Change the Target branch to merge to `main` on game-theory-tools-group/gtnash-git + +* Then fill in the pull request description and click the "Create merge request" button. You may also notify the integration manager that you submitted this pull request. +Once the integration manager has merged it into the `main` branch of the project, and notified it to you, delete your local `fix-dummy` branch. + +#### On the integration manager's side +*It is assumed that the manager has already prepared his private local repository for integration. The remote named origin represents the gtnash reference repository.* + +* Switch to the `main` branch and update changes from the `main` branch on the reference repository +```bash +git checkout main +git fetch origin +git merge origin/main +``` +* Create a local branch for the source code from the developer +```bash +git checkout -b <USERNAME>-fix-dummy main +``` +* Pull the `fix-dummy` branch from the developer public repository +```bash +git pull https://forgemia.inra.fr/<USERNAME>/gtnash-git.git fix-dummy +``` +* Check the merged source code in order to accept or reject it: review code, and run CI and tests +* If accepted, merge it in the `main` branch and push the merged `main` branch to the gtnash reference repository +```bash +git checkout main +git merge <USERNAME>-fix-dummy +git push origin main +``` +* Notify the developers about the updated `main` branch update, or notify the concerned developer about the reject of the proposed development + +## Git ressources + +Git basics: +* [Pro Git Book by Scott Chacon](http://git-scm.com/book) (also available in [french](http://git-scm.com/book/fr)) +* [Git SCM documentation](http://git-scm.com/documentation) +* [Git Immersion](http://gitimmersion.com/) +* [Git Magic](http://www-cs-students.stanford.edu/~blynn/gitmagic/) +* [just a simple guide for getting started](https://rogerdudler.github.io/git-guide/) +* [Learn Git in 30 Minutes](https://tutorialzine.com/2016/06/learn-git-in-30-minutes) +* [Learn git concepts, not commands](https://dev.to/unseenwizzard/learn-git-concepts-not-commands-4gjc) +* [FAQ Git (fr)](https://alm.developpez.com/faq/git/) +* [Débuter avec git](https://carlchenet.com/category/debuter-avec-git/) +* [Become a git guru](https://www.atlassian.com/git/tutorials) +* [Understand the Basics of Git in 8 Minutes](https://blog.theodo.com/2019/08/understand-the-basics-of-git-in-8-minutes/) +* [Git cheatsheet](https://ndpsoftware.com/git-cheatsheet.html#loc=index;) +* [Find the right commands you need](https://gitexplorer.com/) +* [Visualizing git](https://git-school.github.io/visualizing-git/) +* [Flight rules for Git](https://github.com/k88hudson/git-flight-rules) +* [Git for Computer Scientists](https://eagain.net/articles/git-for-computer-scientists/) +* [Patterns and practices for good Git usage](https://blog.isquaredsoftware.com/2021/01/coding-career-git-usage/) +* [Semantic Versioning](https://semver.org/) + +Git branching model and workflow: +* [A successful Git branching model](http://nvie.com/posts/a-successful-git-branching-model/) +* [My Git branching model, by William Durand](http://williamdurand.fr/2012/01/17/my-git-branching-model/) +* [Scott Chacon's Git flow](http://scottchacon.com/2011/08/31/github-flow.html) +* [Learn Git Branching (online interactive env)](https://learngitbranching.js.org/) +* [War of the Git Flows](https://dev.to/scottshipp/war-of-the-git-flows-3ec2) +* [say no to GitFlow](https://reallifeprogramming.com/git-process-that-works-say-no-to-gitflow-50bf2038ccf7) +* [Git team workflow: merge or rebase?](https://ljvmiranda921.github.io/notebook/2018/10/25/git-workflow/) + +Git messages +* [A specification for adding human and machine readable meaning to commit messages](https://www.conventionalcommits.org/en/v1.0.0/) +* [How to Write a Git Commit Message](https://cbea.ms/git-commit/) \ No newline at end of file -- GitLab