{Singularity} is an open source project, meaning we have the challenge of limited resources. We are grateful for any support that you can offer. Helping other users, raising issues, helping write documentation, or contributing code are all ways to help!
This is a huge endeavor, and your help would be greatly appreciated! Post to online communities about {Singularity}, and request that your distribution vendor, service provider, and system administrators include {Singularity} for you!
If you have been using {Singularity} and having good luck with it, join our Google Group and help out other users!
Many of our users come to Slack for quick help with an issue. You can find us at singularity-container.
For general bugs/issues, you can open an issue at the GitHub repo. However, if you find a security related issue/problem, please email the Singularity Security Team directly at singularity-security@hpcng.org. More information about the Singularity security policies and procedures can be found here
We (like almost all open source software providers) have a documentation dilemma… We tend to focus on the code features and functionality before working on documentation. And there is very good reason for this: we want to share the love so nobody feels left out!
You can contribute to the documentation by raising an issue to suggest an improvement or by sending a pull request on our repository for documentation.
The current documentation is generated with:
Other dependencies include:
More information about contributing to the documentation, instructions on how to install the dependencies, and how to generate the files can be obtained here.
For more information on using Git and GitHub to create a pull request suggesting additions and edits to the docs, see the :ref:`section on contributing to the code <contribute-to-the-code>`. The procedure is identical for contributions to the documentation and the code base.
We use the traditional GitHub Flow to develop. This means that you fork the main repo, create a new branch to make changes, and submit a pull request (PR) to the master branch.
Check out our official CONTRIBUTING.md document, which also includes a code of conduct.
To contribute to {Singularity}, you should obtain a GitHub account and fork the
{Singularity} repository. Once forked,
clone your fork of the repo to your computer. (Obviously, you should replace
your-username with your GitHub username.)
$ git clone https://github.com/your-username/singularity.git && \
cd singularity/
Branches are a way of
isolating your features from the main branch. Given that we’ve just cloned the
repo, we will probably want to make a new branch from master in which to work on
our new feature. Lets call that branch new-feature:
$ git checkout master && \
git checkout -b new-feature
Note
You can always check which branch you are in by running git branch.
On your new branch, go nuts! Make changes, test them, and when you are happy commit the changes to the branch:
$ git add file-changed1 file-changed2...
$ git commit -m "what changed?"
This commit message is important - it should describe exactly the changes that you have made. Good commit messages read like so:
$ git commit -m "changed function getConfig in functions.go to output csv to fix #2"
$ git commit -m "updated docs about shell to close #10"
The tags close #10 and fix #2 are referencing issues that are posted on
the upstream repo where you will direct your pull request. When your PR is
merged into the master branch, these messages will automatically close the
issues, and further, they will link your commits directly to the issues they
intend to fix. This will help future maintainers understand your contribution,
or (hopefully not) revert the code back to a previous version if necessary.
When you are done with your commits, you should push your branch to your fork (and you can also continuously push commits here as you work):
$ git push origin new-feature
Note that you should always check the status of your branches to see what has been pushed (or not):
$ git status
Once you have pushed your branch, then you can go to your fork (in the web GUI
on GitHub) and submit a Pull Request. Regardless of the
name of your branch, your PR should be submitted to the Singularity master
branch. Submitting your PR will open a conversation thread for the maintainers
of {Singularity} to discuss your contribution. At this time, the continuous
integration that is linked with the code base will also be executed. If there is
an issue, or if the maintainers suggest changes, you can continue to push
commits to your branch and they will update the Pull Request.
Cloning the repo will create an exact copy of the {Singularity} repository at that moment. As you work, your branch may become out of date as others merge changes into the upstream master. In the event that you need to update a branch, you will need to follow the next steps:
$ git remote add upstream https://github.com/hpcng/singularity.git && # to add a new remote named "upstream" \
git checkout master && # or another branch to be updated \
git pull upstream master && \
git push origin master && # to update your fork \
git checkout new-feature && \
git merge master