-
Notifications
You must be signed in to change notification settings - Fork 87
Contributing
Hubble uses semantic versioning MAJOR.MINOR.PATCH numbers. We try (although loosely) to indicate major changes with MAJOR numbers. Major changes being those that make the program different enough that it's no-longer "backwards compatible." MINOR numbers indicate relatively large changes that add new functionalities (but don't significantly change the install requirements or config languages). And PATCH number changes are used for bugfixes and other problem-based increments.
The master branch represents the current version and it's PATCH number changes. The develop branch represents the next release (whether MAJOR or MINOR).
Where possible, please submit new PRs against the earliest applicable version branch. Pretend we're working on a 4.1.0 release in develop, the last release was 4.0.0 and we're working on a 4.0.1 release in master, and that we still support a 3.0.13 release in the 3.0 branch.
A bugfix that applies to 3.0.13 should be submitted as a PR against the 3.0 branch. We can then copy the fix forward to master and then to develop. A new patch that applies to 4.0.x to 3.0.x would be submitted against master and a bugfix that somehow doesn't apply to any released version or a new feature would be submitted against the develop branch.
Any new features should target develop as the base branch. There may be exceptions or good reasons why a new feature should target a release branch. If it seems obvious or necessary that a feature would need to affect a release branch, please describe the reasons in the PR description.
Where possible, please make sure the unit tests cover your new feature or bugfix and that the new tests pass. Please also make sure no other tests begin failing due to your new code. Please also make sure any files changed in your PR pass the linting (as described in our pylintrc in the repo).
Most likely we won't be able to merge a PR that doesn't lint well or pass the unit tests.
We have a jenkins process that runs linting and testing against all new PRs. When it's working (most of the time) it should attach comments to the end of the PR.
When your new feature or bugfix is complete and it's just about time to submit it; please be kind and rebase before you submit. If you've never rebased before, the simplest way to proceed is with a git pull --rebase upstream branchname. The first goal is just to make sure your new changes are submitted against the most current state of things in the repo. During the rebase you may encounter conflicts that it's certainly better for the author to resolve than a maintainer. The second goal is to tell the right story.
A Pull Request isn't just a bucket where you toss commits chum and detritus. It should be a short list of changes with comments that tell the story of why the change exists and what's happening in the PR. Before your initial upload, be sure to at least consider issuinggit rebase -i upstream/branchname. Get those 'typo' and 'oops' comments out of there and squash them down into logical commits with (at the very least) a subject line that makes sense.
Lastly, please make sure your PR is free of any merge commits, revert commits or other history changes that could be hidden or removed with a rebase. These sorts of maintenance commits have no place in a PR -- there are exceptions, but they are exceedingly rare.
You may have read that it's important not to re-write history; this is definitely true for any shared branch. This is the main reason feature branches created for PRs live in your personal repo and never in the main repo. If someone other than yourself checks out a PR branch and you later rebase or alter the branch, then this third party checkout will not go very well -- they'll have to reset their branch to get it to fast-forward/merge correctly.
While we recommend git rebase -i upstream/branchname; it's worth noting that you must never squash commits by someone else and never squash commits that are already in the history of the upstream branch. If everything has been developed in a typical fashion, this will not be an issue and really shouldn't come up. If you've historically used git merge repeatedly and indiscriminately, your non-linear history may just present other people's commits (or commits from the upstream) in your edit history. Do not squash these, find some other way to resolve the history problem.
Presuming you've been careful to keep your feature branch history linear, you should be able to semi regularly issue git pull --rebase upstream branchname to get your feature branch up to date. This will certainly require you to force push the feature branch git push -f myrepo branchname which will automagically update your PR. Remember that force pushing has a bad reputation only for shared branches. For single user PR branches, it is absolutely necessary to present a clean PR.
When asked to update a PR to squash some commits, clean up history, or make any other changes (including bash branch changes!); do not close and resubmit your PR! This will only result in the developers having to close your new one and re-open your old one. All changes to a PR can be made without closing it.