Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Cobra User Contract #1292

Merged
merged 2 commits into from Jan 26, 2021
Merged

Cobra User Contract #1292

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7cda2ce
Add some guiding principals to the project.
jharshman Dec 4, 2020
fe5b022
grammatical errors
jharshman Dec 4, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
37 changes: 37 additions & 0 deletions CONDUCT.md
View file
Open in desktop
@@ -0,0 +1,37 @@
## Cobra User Contract

### Versioning
Cobra will follow a steady release cadence. Non breaking changes will be released as minor versions quarterly. Patch bug releases are at the discretion of the maintainers. Users can expect security patch fixes to be released within relatively short order of a CVE becoming known. For more information on security patch fixes see the CVE section below. Releases will follow [Semantic Versioning](https://semver.org/). Users tracking the Master branch should expect unpredictable breaking changes as the project continues to move forward. For stability, it is highly recommended to use a release.

### Backward Compatibility
We will maintain two major releases in a moving window. The N-1 release will only receive bug fixes and security updates and will be dropped once N+1 is released.

### Deprecation
Deprecation of Go versions or dependent packages will only occur in major releases. To reduce the change of this taking users by surprise, any large deprecation will be preceded by an announcement in the [#cobra slack channel](https://gophers.slack.com/archives/CD3LP1199) and an Issue on Github.

### CVE
Maintainers will make every effort to release security patches in the case of a medium to high severity CVE directly impacting the library. The speed in which these patches reach a release is up to the discretion of the maintainers. A low severity CVE may be a lower priority than a high severity one.

### Communication
Cobra maintainers will use GitHub issues and the [#cobra slack channel](https://gophers.slack.com/archives/CD3LP1199) as the primary means of communication with the community. This is to foster open communication with all users and contributors.

### Breaking Changes
Breaking changes are generally allowed in the master branch, as this is the branch used to develop the next release of Cobra.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm curious about this. It seems to indicate that once a release is out, the master branch can accept breaking changes such as removing functions.

But such changes will break clients at the next release, so I wonder if that is really what the sentence aims to convey?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@marckhouzam, this sentence does feel a bit off. The point we are trying to convey here is that breaking changes should only show up in major releases. Where we keep those breaking changes til then is a matter of discussion.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

although... this might be fine if we consider that we might create release branches that are maintained through their lifecycle.
In that case all changes hit master and are then merged into the currently maintained release branch and published as minor releases until the next major release.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That would work. But as you point out every PR would need to come in for the release branch and the master branch (except breaking PRs, but those are rare anyway).

Also, it makes me wonder about patch releases. Would there be any? If so, from what branch would they be built?

If you're interested, here's the way helm does its release strategy.

  • a minor release triggers a new release branch. After the release only bug fixes go in that release branch for future patch releases
  • the master branch is then used for the next minor release, so PRs target the master branch (which is simple for new contributors) and only bug fixes need to be cherry-picked into the release branch (this is relatively simple and is done by the maintainer on the patch release day, based on a PR tag)
  • breaking changes are not committed anywhere but instead the PR is scheduled for the next major milestone; this works well because breaking changes are rare

I feel this is a pretty simple process but it could be that I'm used to it 😁


There may be times, however, when master is closed for breaking changes. This is likely to happen as we near the release of a new version.

Breaking changes are not allowed in release branches, as these represent minor versions that have already been released. These version have consumers who expect the APIs, behaviors, etc, to remain stable during the lifetime of the patch stream for the minor release.

Examples of breaking changes include:
- Removing or renaming exported constant, variable, type, or function.
- Updating the version of critical libraries such as `spf13/pflag`, `spf13/viper` etc...
- Some version updates may be acceptable for picking up bug fixes, but maintainers must exercise caution when reviewing.

There may, at times, need to be exceptions where breaking changes are allowed in release branches. These are at the discretion of the project's maintainers, and must be carefully considered before merging.

### CI Testing
Maintainers will ensure the Cobra test suite utilizes the current supported versions of Golang.

### Disclaimer
Changes to this document and the contents therein are at the discretion of the maintainers.
None of the contents of this document are legally binding in any way to the maintainers or the users.