Contributing to the IGWN Computing Guide¶
This page outlines the recommended procedure for reporting issues / giving feedback on the computing guide, or proposed new or modified content.
Reporting issues / feedback¶
To report issues, or post feedback, please open a ticket by navigating to
https://git.ligo.org/computing/guide/-/issues/new
Making contributions¶
To make a contribution, please follow the fork and merge request workflow. This will ensure that your changes do not break the rendering of the site, and also adhere to the best practices of the Markdown document style.
All source files for documentation should be written in markdown format, consistent with the syntax and style rules outlined in STYLE.md.
1. Make a fork (copy) of the guide repository¶
You only need to do this once:
- Go to the repository home page,
- click on the Fork button, that should lead you here,
- select the namespace that you want to create the fork in, this should usually be your personal namespace.
If you can't see the Fork button, make sure that you are logged in by checking for your account profile avatar in the top right-hand corner of the screen.
Clone your fork¶
Clone your fork with
git clone git@git.ligo.org:<namespace>/guide.git
and add the upstream repository as a remote:
cd guide
git remote add upstream git@git.ligo.org:computing/guide.git
Making changes¶
All changes should be developed on a feature branch in order to keep them separate from other work, thus simplifying the review and merge once the work is complete. The workflow is:
-
Create a new feature branch configured to track the
main
branch of theupstream
repository:git fetch upstream git checkout -b my-new-feature upstream/main
These commands fetch the latest changes from the
upstream
remote, then create the new branchmy-new-feature
based offupstream/main
, and checks out the new branch. There are other ways to do these steps, but this is a good habit since it will allow you tofetch
andmerge
changes fromupstream/main
directly onto the branch. -
Develop the changes you would like to introduce, using
git commit
to finalise a specific change. Ideally commit small units of change often, rather than creating one large commit at the end, this will simplify review and make modifying any changes easier.Commit messages should be clear, identifying which code was changed, and why. Common practice is to use a short summary line (<50 characters), followed by a blank line, then more information in longer lines.
-
Push your changes to the remote copy of your fork on https://git.ligo.org. The first
push
of any new feature branch will require the-u/--set-upstream
option topush
to create a link between your new branch and theorigin
remote:git push --set-upstream origin my-new-feature
Subsequent pushes can be made with
git push origin my-new-feature
-
Keep your feature branch up to date with the
upstream
repository by doing.git checkout my-new-feature git pull --rebase upstream main git push --force origin my-new-feature
If there are conflicts between
upstream
changes and your changes, you will need to resolve them before pushing everything to your fork.
Open a merge request¶
When you feel that your work is finished, you should create a merge request to propose that your changes be merged into the main (upstream
) repository.
After you have pushed your new feature branch to origin
, you should find a new button on the repository home page inviting you to create a merge request out of your newly pushed branch. (If the button does not exist, you can initiate a merge request by going to the Merge Requests tab on your fork website on git.ligo.org and clicking New merge request)
You should click the button, and proceed to fill in the title and description boxes on the merge request page.
Once the request has been opened, one of the maintainers will assign someone to review the change. There may be suggestions and/or discussion with the reviewer. These interactions are intended to make the resulting changes better. The reviewer will merge your request.
Once the changes are merged into the upstream repository, you should remove the development branch from your clone using.
git branch -d my-new-feature
A feature branch should not be repurposed for further development as this can result in problems merging upstream changes.