VivumLab recognises that an open source project is only as strong as its community. For this reason we want to make contributing to this project as easy and transparent as possible, whether it is:
- Reporting a Bug
- Discussing the current state of the code
- Submitting a fix
- Proposing new features
- Testing (security or otherwise)
- Design (graphic, web or otherwise)
- Investing yourself, and becoming a recognised contributor
We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.
VivumLab follows a common FOSS development workflow. A core group of maintainers handle the branching, merging and tagging of releases. While this core group shepherds the overall project, everyone is welcome to contribute. This document goes into detail on how you can contribute.
Report bugs, offer suggestions, make requests, all by opening a new issue; it's that easy! Here are some guidelines to make your issue submissions better for the community.
!!! NOTE: No change happens without a prefacing issue, simple.
Write issues with detail, background information, and sample code if applicable. Keep background information relevant to the issue, and do not share personal information. Gather feedback from the community; have patience, wait a day or two before beginning work
Bug reports are a staple of software development. When submitting a bug report, make sure to include (where applicable):
- a quick summary and/or background information
- steps to reproduce (be specific)
- what you expected to happen
- what actually happens
- if appropriate, try to include:
- sample code
- installed software (include versions)
- options you tried (but didn't work)
VivumLab acknowledges that sometimes bugs are not the fault of VivumLab code but rather the fault of the software used to make VivumLab possible. This is not a reason to debate or fault:
- persons
- companies
- communities
Instead, find a workaround and suggest it to the community. VivumLab may also be able to assist other users in automating your suggested workaround; pretty cool, right?
Pull requests, or PRs are the best way to propose changes to the codebase, though all PRs will need to be prefaced with an issue. Also there are commit rules in place, that must be followed. Be sure to speak to a community leader, if you are unsure.
A good PR is small and changes as few lines of code as possible to resolve the issue. Multiple smaller separate PRs are ofter better than one big PR that touches multiple areas of the code.
A large PR with several unrelated fixes in it can contain code that may cause issues with the VivumLab codebase; effectively stopping the rest of the code from being merged.
Ultimately, smaller PRs are easier to review, test, track, and merge.
While we actively welcome your PRs, a successful contribution to the project is not guaranteed. The PR will be reviewed by VivumLab Community Leaders, discussions will ensue, and only after appropriate deliberation will the PR be merged. This is only to ensure the quality of code; it is nothing personal.
To contribute to VivumLab, you'll need to:
- Establish and maintain a mirrored Fork
- Branch Dev in your fork
- Develop your feature/fix
- Commit to your branch on your fork
- Create a Merge Request
Doing the above will require some prior knowledge; you'll need a working understanding of Git, and a GitHub account. Understanding Git has a small learning curve and is unfortunately, beyond the scope of this document.
!!!NOTE: The following instructions are provided as a guideline, and is by no means, definitive, Follow the link, do some research.
-
Create your own fork by clicking the "Fork" button at https://github.com/Vivumlab/VivumLab:
-
In your fork, goto Settings/Repository -> "Mirroring repositories" and setup mirroring of Vivumlab/VivumLab
Mirror direction = Pull Only mirror protected branches = enabled
-
Then set your Protected Branches in Settings/Repository -> "Protected Branches" like this
(you can ignore CODEOWNER though) you can even set push to "no one" so you can't accidentally push to that branch.
- Make sure you don't have any outstanding un-related changes in your local repository with
git status; You should seenothing to commit, working tree clean. - Identify the branch name by navigating to the issues' linked Merge Request and clicking the copy icon next to the Branch name.
- Run
git fetch origin - Run
git checkout <<branch name>> - Make your changes
- Commit and Push
Fixing issues announced by the community is the backbone of this project. What happens when you find an issue that you know how to fix, but no one has made a PR to fix it? Here's how you should do it
- Make sure you don't have any outstanding un-related changes in your local repository with
git status. You should seenothing to commit, working tree clean. - Locate the appropriate issue, and from this issue, click the
Create Merge Requestbutton. - Now click the
Check Out Branchbutton and rungit statusagain on your local copy of the repository. - Now make your changes, commit and push them.
- On GitHub, go to your PR and make sure it is not labeled WIP and that all the check boxes are checked (If applicable).
Once you've submitted the PR, community leaders will review it. Only once it is approved, will it be merged.
At this point, nothing else is required from you, unless specifically requested. Don't worry about rebasing, or closing the merge request.
If the Merge Request needs changes, the maintainers will add comments describing the needed changes, the label WIP: will be added to the start of the title, and the submitter will be reassigned to the PR.
If/When you are asked to rebase, run:
git checkout dev
git pull
git checkout <branch name>
git rebase dev
We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history. But also, we use the git commit messages to generate the changelog.
The commit message formatting can be added using a typical git workflow or through the use of a CLI wizard for example (Commitizen).
Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
The header is mandatory and the scope of the header is optional.
Any line of the commit message cannot be longer than 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.
If the commit reverts a previous commit, it should begin with revert: , followed by the header
of the reverted commit.
In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit
being reverted.
Must be one of the following:
- feat: A new feature
- fix: A bug fix
- docs: Documentation only changes
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- refactor: A code change that neither fixes a bug nor adds a feature
- perf: A code change that improves performance
- test: Adding missing or correcting existing tests
- chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
The scope could be anything specifying place of the commit change. For example service,
core, docs, etc...
The subject contains succinct description of the change:
- use the imperative, present tense: "change" not "changed" nor "changes"
- don't capitalize first letter
- no dot (.) at the end
Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.
The footer should contain any information about Breaking Changes and is also the place to [reference GitHub issues that this commit closes][closing-issues].
Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines.
The rest of the commit message is then used for this.
You can play around with the stack locally without needing an actual server to spin it up against.
First run make config as normal. The local IP and SSH username are not used for Vagrant, so they can be
for your real server, or fake. For What is the domain you have pointed at your Vivumlab server with ports 80 and 443?:
enter localhost.
Now run make develop to spin up a local instance inside a Vagrant machine.
For easy access to the services run vagrant ssh -c "cat {{ volumes_root }}/vivumlab_hosts". Append the output of this to your
machine's host file (usually /etc/hosts). Now you should be able to access http://servicename.localhost:2280/
where servicename is the name of any services you have enabled in config.yml.
If you make changes to the Ansible scripts you can run make provision to run them again.
To deploy just one service you can run make update_one SERVICE_NAME e.g. make update_one zulip
To run just one set of tags you can run make tag TAG_NAME e.g. make tag tinc
[client]$ make web - Spins up a development stack
[client]$ make lint - Run linting scripts
To serve the docs locally run make docs_local.
To work on the VivumLab website just type make web to serve it locally.
This should go without saying but when you submit any contribution, including but not limited to: code additions, code changes, images, documentation, audio, and video; your submissions are assumed to be under the same license that covers the project.
Feel free to contact a Community Leader if that's a concern.
By contributing, you agree that your contributions will be licensed under its MIT License.
Please see Legal/ Licensing/ Acknowledgement