Git workflow

Configuration

The following explains conventions on how to synchronize and contribute to the repository. It follows the feature-branch paradigm.

Create a fork on github (once)

To create a fork in your Github space, go to the main project page and click on the "Fork" button on the top right. Refer to this help page to know more about the fork process.

This forked repository will be where you upload the modifications you have made locally. Then you issue a pull request (PR) to the main repository. This PR has to be reviewed before being merged in the main branch (see section "Normal workflow").

The main repository and your fork version are called "remotes".

Initialize local repository (once)

On your machine, the following will get the current version of the main github repository:

git clone https://github.com/lesca-research/pulsage

Remotes

Configure remote repos:

git remote -v # show all remote repo

The origin repository (main official github repository) should already bet set to https://github.com/lesca-research/pulsage.

Add your fork repository as the upstream remote (replace user_name with your user name).

Using ssh::

git remote add upstream git@github.com:user_name/pulsage.git #my fork of repo (forked on github), uses ssh

Using https::

git remote add upstream https://github.com/user_name/pulsage.git git@github.com:user_name/pulsage.git

To locally checkout pull requests (PRs)

In the file pulsage/.git/config, section origin, add the line fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

Normal Workflow

Prepare new feature -> describe the feature on GitHub with a ticket or assign yourself to an existing one	open a new issue on GitHub and label it or work on existing ticket
Start a new feature -> create a new descriptively-named branch	git checkout -b new-dev
Write doc, tests, implement -> Declare files to be commited	git add new_dev.rst test_new_dev.py new_dev.py
When a sub-stuff seems completed -> commit locally	git commit -m '[#<ticket_number>] my stuff started'
Loop while working	git add ... ; git commit -m '[#<ticket_number>] ...'
Before pushing upstream, check that you are up to date with master branch in main repository.	git fetch origin; git checkout main; git merge origin/main
If previous command updated your master branch rebase your feature branch on master. Resolve conflicts if any.	git checkout new-dev; git rebase main
When the feature is ready to publish -> push to your fork of nirstorm on your github	git push upstream new-dev
To ask for feedback and for merge on master -> do a pull-request on Github -> indicate that the PR is closed	Login to your github account an open a Pull-request from it
Someone else review your PR they have to checkout the PR	git cmds: git fetch origin git checkout pr/<PR_ID>
If someone else wants to checkout updated PR	git cmds: git fetch origin git checkout pr/<PR_ID> git merge origin/pr/<PR_ID>
See comments on the PR on github Wait for close or approval
Once PR is treated, if merge occured switch to master branch update master from official repo	git cmds: git checkout main git pull origin
Close the dev of the new feature locally on github	git cmds: git branch -d new-dev git push upstream --delete new-dev

Sketch of the workflow:

## official repo on Github ##                          ## fork on user account ##
 pulsage:pulsage/main            /_____PR______        __  user:pulsage/my-branch
                                 \                      /\
             \                                         /
      git pull origin                 git push upstream my-branch
                \                                 /
                _\|      ## local repo  ##       /
             origin/main                upstream/my-branch

Misc useful commands

• Show a nice history log:

  git log --oneline --decorate --color --graph
  git log --pretty=format:"%C(auto)%h %ar %d %s %C(bold blue)<%an>%Creset" --decorate --color --graph
  

• You can also add an alias:

  git config --global alias.hist 'log --pretty=format:"%C(auto)%h %ar %d %s %C(bold blue)<%an>%Creset" --decorate --color --graph'
  git hist