Newer
Older
# 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
* 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).
* 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), 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
```
* 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
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
```
* 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
* 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 fix-dummy
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
```
* 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/)