This guide is written for contributing to documentation. It doesn't contain any instructions on installing software prerequisites. If your intended contribution requires any software installations, please refer to their respective official documentation.
Prerequisites
Git installed on your local machine
GitHub account
Contents
PR Contribution Workflow
Basic Workflow Example
PR Acceptance policy
Fork and clone this repository (git clone
)
Create a feature branch against master (git checkout -b featurename
)
Make changes in the feature branch
Commit your changes (git commit -am "Add a feature"
)
Push your changes to GitHub (git push origin feature
)
Open a Pull Request and wait for your PR to get reviewed
Edit your PR to address the feedback (if any)
See your PR getting merged
In order to contribute, you need to make your own copy of the repository you're going to contribute to. You do this by forking the repository to your GitHub account and then cloning the fork to your local machine.
Fork this GitHub repository: on GitHub, navigate to the main page of the repository and click the Fork button in the upper-right area of the screen. This will create a fork (a copy of this repository in your GitHub account).
Clone the fork and switch to the project directory by running in your terminal:
2. Create a New Branch
It is important to make all your changes in a separate branch created off the master branch.
Before any modifications to the repository that you've just cloned, create a new branch off of the master branch.
Create a new branch off of the current one and switch to it:
To switch between branches, use the same command without the -b
flag. For example, to switch back to the master branch:
This way you can switch between multiple branches when you work on multiple features at once.
Branch Naming Conventions
Give your branch a descriptive name so that others working on the project understand what you are working on. The branch name should include the name of the module that you're contributing to.
Name your branch according to the following template, replacing nginx
with the name of the module you're contributing to:
Make changes you want to propose. Make sure you do this in a dedicated branch based on the master branch.
Commit changes often to avoid accidental data loss. Make sure to provide your commits with descriptive comments.
Or add and commit all changed files with one command:
Push your local changes to your fork on GitHub.
For example, if your remote repository is called origin and you want to push a branch named docs/fix:
Navigate to your fork on GitHub. Press the "New pull request" button in the upper-left part of the page. Add a title and a comment. Once you press the "Create pull request" button, the maintainers of this repository will receive your PR.
After you submit the PR, one or several of the Hydrosphere repository reviewers will provide you with actionable feedback. Edit your PR to address all of the comments. Reviewers do their best to provide feedback and approval in a timely fashion but note that response time may vary based on circumstances.
Once your PR is approved by a reviewer, it gets accepted and merged with the main repository. Merged PRs will get included in the next Hydrosphere release.
What will make your PR more likely to get accepted:
Having your fixes on a dedicated branch
Proper branch naming
Descriptive commit messages
PR title describing what changed
PR comment describing why/where it changed in <80 chars
Texts checked for spelling and typos (you can use Grammarly)
Code snippets checked with linters (when applicable)
A PR title should describe what has changed. A PR comment should describe why and what/where. If your changes relate to a particular issue, a PR comment should contain an issue number. Please keep PR comments below 80 characters for readability.
PR title example:
PR comment example:
Minor edits (typos, spelling, formatting, adding small text pieces) may get waved through. More substantial changes normally require more time, reviewers, and back-and-forths, and you might get asked for a PR resubmission or dividing changes into more that one PR. Usually, PRs are getting merged right after the approval.