## A Project Contribution Workflow
*Chiara Marmo, LISN - Université Paris Saclay*
---
## Version Control Systems (VCS)
---
### What is a version control system?
A VCS is a tool first used in software development
- to keep track of source modifications (and their authors)
- to allow parallel developments and experimenting
---
It provides
- a mechanism to identify the position in the editing history
(eg a label or a color in the history graph)
- a mechanism to merge different histories
---
### Why use a version control system?
- Reproducibility : identify which version produced wich results
- Traceability : revert and track errors
- Collaboration : allow asyncronous and remote work on the same code
- Innovation : allow experimenting on different versions
---
### Some version control systems
[List and comparison](https://en.wikipedia.org/wiki/Comparison_of_version-control_software)
Sage used [Mercurial](https://www.mercurial-scm.org/), it has moved to [git](https://git-scm.com/) today.
Both are [distributed VCS](https://en.wikipedia.org/wiki/Distributed_version_control)
---
## Forges and Cloud hosted repositories
---
### What is a Software Forge?
A forge is a cloud based or on premises service
- to host the sources as authoritative repository
- to manage bug reports, issue trackers and more generally the management of the project
---
It provides
- a user-friendly interface for basic versioning operations (edit, commit, merge, etc)
- dedicated tools for project management
- dedicated tools for continuous integration and development, package releases, documentation deployement, etc
- authentication and access management
---
### Why use a Forge?
- Accessibility : identify a reference repository for the project
- Security : manage access athorizations to the main repository
- Transparency : manage issues and contributions openly for all the contributors
- Planning : set milestones and tasks for the project to evolve
---
### Some forges
| **Cloud Based** | **On-premises** |
| ------------------------------------------ | ----------------------------------- |
| [GitHub](https://github.com/) | |
| [GitLab.com](https://gitlab.com/public) | [GitLab](https://about.gitlab.com/) |
| [CodeBerg](https://codeberg.org/) | [ForgeJo](https://forgejo.org/) |
| [FOSS HeptaPod](https://foss.heptapod.net) | [HeptaPod](https://heptapod.net/) |
| [GiTea](https://gitea.com/) | [GiTea](https://about.gitea.com/) |
---
- Sage is hosted on GitHub :
https://github.com/sagemath/sage
- Paris Saclay University Forge :
https://gitlab.dsi.universite-paris-saclay.fr
- IN2P3 CNRS Forge :
https://gitlab.in2p3.fr
---
## Contributing
Cloning a [repository](https://gitlab.dsi.universite-paris-saclay.fr/chiara.marmo/sage-days-contributing-slides) from the forge
```bash
$ git clone https://gitlab.dsi.universite-paris-saclay.fr/chiara.marmo/sage-days-contributing-slides.git
Cloning into 'sage-days-contributing-slides'...
remote: Enumerating objects: 4, done.
remote: Counting objects: 100% (4/4), done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 4 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
Receiving objects: 100% (4/4), done.
$ cd sage-days-contributing-slides
$ git status
On branch master
Your branch is up to date with 'origin/master'.
nothing to commit, working tree clean
```
---
Making changes locally
```bash
$ git branch my-new-branch
$ git switch my-new-branch
Switched to branch 'my-new-branch'
$ git branch --list
master
* my-new-branch
$ echo "One more line." >> README.md
$ git status
On branch my-new-branch
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: README.md
no changes added to commit (use "git add" and/or "git commit -a")
```
---
Configure your local repo
```bash
$ git config user.name "My Name"
$ git config user.email "my.name@universite-paris-saclay.fr"
```
Commit your changes
```bash
$ git commit -a -m "My first change"
[my-new-branch 5aafdc7] My first change
1 file changed, 1 insertion(+)
```
Or
```bash
$ git add README.md
$ git commit -m "My first change"
```
See more about the [staging area](https://git-scm.com/about/staging-area)
---
Push your changes
```bash
$ git remote -v
origin https://gitlab.dsi.universite-paris-saclay.fr/chiara.marmo/sage-days-contributing-slides.git (fetch)
origin https://gitlab.dsi.universite-paris-saclay.fr/chiara.marmo/sage-days-contributing-slides.git (push)
$ git push origin my-new-branch
Username for 'https://gitlab.dsi.universite-paris-saclay.fr':
```
Do you have an account there? Are you authorized to push to the repository?
---
### Forking on the forge
Now you can clone from your fork and you have complete control on your repository.
---
Forking is a forge relation: how to connect with the forked repository locally?
```bash
$ git remote -v
origin https://gitlab.dsi.universite-paris-saclay.fr/your.user/sage-days-contributing-slides.git (fetch)
origin https://gitlab.dsi.universite-paris-saclay.fr/your.user/sage-days-contributing-slides.git (push)
$ git remote add upstream https://gitlab.dsi.universite-paris-saclay.fr/chiara.marmo/sage-days-contributing-slides.git
$ git remote -v
origin https://gitlab.dsi.universite-paris-saclay.fr/your.user/sage-days-contributing-slides.git (fetch)
origin https://gitlab.dsi.universite-paris-saclay.fr/your.user/sage-days-contributing-slides.git (push)
upstream https://gitlab.dsi.universite-paris-saclay.fr/chiara.marmo/sage-days-contributing-slides.git (fetch)
upstream https://gitlab.dsi.universite-paris-saclay.fr/chiara.marmo/sage-days-contributing-slides.git (push)
```
---
### Merge or Pull Requests
- Read the `CONTRIBUTING.md` or any other contributor documentation
- Choose a clear and synthetic title
- Explain more details in the description: why the MR/PR is needed, is fixing an open issue, ...
- Be polite
---
| command | use |
| ------------ | ------------------------------------------------------ |
| `git clone` | download and configure the repo |
| `git status` | show the status of the repo |
| `git branch` | manage the branches |
| `git switch` | switch to a new branch |
---
| command | use |
| ------------ | ------------------------------------------------------ |
| `git remote` | manage the remotes |
| `git add` | add modifications to the staging area |
| `git commit` | commit modifications (create a new label for the node) |
| `git push` | push changes to the remote |
---
| command | use |
| ------------ | ------------------------------- |
| `git fetch` | retrieve labels from remote |
| `git merge` | merge branches |
| `git pull` | fetch and merge a specific branch|
| `git checkout` | update files in the working tree |
| `git rebase` | redefine the reference point for changes |
---
### never to be used ... even if ChatGPT told you so
`git reset --hard`
---
### Play with branches
https://learngitbranching.js.org/
{"tags":"SageMath, LISN","title":"Sage Days @ LISN 2025 - Contribution Workflow"}