IGWN Metapackages User Guide¶

How to install the metapackages¶

The metapackages are included in the software distributions maintained by the IGWN Computing and Software Group. See the supported 'Repositories' linked from the IGWN Software Overview on the IGWN Computing Guide for full details of how to configure your package manager to discover the metapackages.

CONTRIBUTING.md

The following is a verbatim copy of CONTIBUTING.md from the IGWN Metapackages repository.

Reporting Issues¶

If you have a GitLab account, please report issues directly through gitlab. Otherwise, you can use the service desk address contact+packaging-metapackages-602-issue-@support.ligo.org to send bug reports by e-mail.

In either case, please include as much detail as possible to reproduce the error, including information about your operating system and the commands you used that led you to the error. If possible, please include a brief, self-contained code example that demonstrates the problem.

Note that when an issue is marked as 'confidential', currently this means that most internal users will also not be able to see it, but only a small number of people with reporter, developer or maintainer status.

Contributing to the metapackages¶

All contributions to the IGWN Metpackages configuration must be made using the fork and merge request workflow, which must then be reviewed by one of the project maintainers.

If you wish to contribute new code, or changes to existing code, please follow this development workflow:

Make a fork (copy) of `computing/packaging/metpackages`¶

You only need to do this once

Go to the IGWN Metapackages 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 will 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 photo in the top right-hand corner of the screen.

Clone your fork¶

Then, clone your fork with

git clone git@git.ligo.org:<namespace>/metapackages.git

Keeping your fork up to date¶

Link your clone to the main (upstream) repository so that you can fetch and pull changes, merge them with your clone, and push them to your fork. Do not make changes on your main branch.

Link your fork to the main repository:

cd metapackages
git remote add upstream git@git.ligo.org:computing/packaging/metapackages.git

You need only do this step once.

Update your main branch to track changes from upstream:

git checkout main
git fetch upstream
git branch --set-upstream-to upstream/main
git pull

You only need to do this step once.

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:
```
git checkout main
git pull
git checkout -b my-new-feature upstream/main
```
This command creates the new branch my-new-feature, sets up tracking the upstream repository, 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 to fetch and merge changes from upstream/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.

Always include a changelog entry

All changes to any of the metapackages must include a changelog entry inserted at the top of the existing changelog. This new entry must include a timestamp in the correct format, and should have a version that matches the timestamp.
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 to push to create a link between your new branch and the origin remote:
```
git push --set-upstream origin my-new-feature
```
Subsequent pushes can be made with just:
```
git push
```
Keep your feature branch up to date with the upstream repository by doing:
```
git pull --rebase upstream main
git push --force origin my-new-feature
```
This works if you created your branch with the checkout command above. If you forgot to add the upstream/main starting point, then you will need to dig deeper into git commands to get changes and merge them into your feature branch.

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 IGWN Metapackages 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. It is recommended that you check the box to Remove source branch when merge request is accepted; this will result in the branch being automatically removed from your fork when the merge request is accepted.

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.