[Moller_simulation] [EXTERNAL] Remoll repository: forking now encouraged

[Wouter Deconinck]

Hi everyone,

I am writing with a change to how we have been using the remoll repository.
We will be moving to a *forking workflow*. Details below.

Cheers,
Wouter


*Summary*: Until now, we mainly have been using branches in the
jeffersonlab/remoll repository on github. Instead of creating branches
there, we will now encourage you to *fork* the remoll repository and create
branches in your own repository. From those branches, you are encouraged to
submit a *pull request* to the jeffersonlab/remoll repository for merging.

*Rationale*: JLab is preferring the forking workflow for users who
contribute to a few repositories only. Membership in the jeffersonlab
organization is reserved for maintainers (and has additional requirements
since these accounts are publicly affiliated with JLab; i.e. real name and
institutional affiliation in your github profile). Moreover, we have enough
contributors now and this workflow scales better.

*Creating a fork*: Click the 'fork' button on the top right of the remoll
repository. You can now clone this repository:
  git clone git at github.com:USERNAME/remoll.git
This will fork all current branches in the jeffersonlab/remoll repository.

*Keeping your fork up to date*:
- Add the upstream repository jeffersonlab/remoll to your list of remotes
(you only need to do this once):
  git remote add upstream https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_jeffersonlab_remoll.git&d=DwIBaQ&c=CJqEzB1piLOyyvZjb8YUQw&r=hK0qfHtfdwUHlZG0DnK-QRJVYus_TzTB8u52ev2QBtI&m=qLh8aBSe_uGXWSxhW3QddWpTzgkToJIgmQGUiB8kcxM&s=WTVvn8-uNQxTmJ9dM8CfWO9KIkFsKbP05tPyBawVxn0&e= 
- Whenever you want to update, fetch the latest upstream changes:
  git fetch upstream
  Variant: git fetch --all
- ... and merge the upstream branch in your branch, e.g. for the 'develop'
branch
  git checkout develop
  git merge upstream/develop
Avoid making changes directly on master or develop, even in your own
repository (for the same reasons).

*Doing your work*:
It is easiest to do your work in branches, one per logically separate
tasks, and to merge those to jeffersonlab/remoll frequently.
- Create a new branch from the develop branch (the base of your branch):
  git checkout develop
  git branch new-feature-xyz
  git checkout new-feature-xyz
- Now, you can do your work in this branch.
- Periodically, push the changes to your repository:
  git push

*Cleaning up your work*:
Before contributing your changes back to jeffersonlab/remoll for others to
use, it make sense to clean up some.
- Make sure your branch works with the most up to date code in the upstream
base branch:
  git fetch upstream
  git checkout develop
  git merge upstream/develop
- Rebase your branch to point to the most recent code in the base branch:
  git checkout new-feature-xyz
  git rebase develop
The rebase phase is when you may need to resolve some conflicts: when you
have modified lines that someone else has modified upstream as well. Ask in
Slack if you need help resolving conflicts (in git; we can't help with the
neighbors).

*Submitting a pull request*:
When you are done with your work in a branch and ready to share it with
others, go to your branch page on GitHub and click the 'pull request'
button. Write a clear summary and wait for someone to merge it (or request
some changes, if necessary). After your branch has been merged, you can go
ahead and delete it. When you update your develop branch, the changes will
be included.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mailman.jlab.org/pipermail/moller_simulation/attachments/20210308/7fb94483/attachment.html>