Skip to content

Commit e08c86c

Browse files
committedJul 19, 2020
Add release policy
1 parent 4475806 commit e08c86c

File tree

1 file changed

+46
-0
lines changed

1 file changed

+46
-0
lines changed
 

‎docs/major_releases/release_policy.md

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# isort Project Official Release Policy
2+
3+
isort has moved from being a simple hobby project for individuals to sort imports in their Python files
4+
to an essential part of the CI/CD pipeline for large companies and significant Open Source projects.
5+
Due to this evolution, it is now of increased importance that isort maintains a level of quality, predictability, and consistency
6+
that gives projects big and small confidence to depend on it.
7+
8+
## Formatting guarantees
9+
10+
With isort 5.1.0, the isort Project guarantees that formatting will stay the same for the options given in accordance to its test suite for the duration of all major releases. This means projects can safely use isort > 5.1.0 < 6.0.0
11+
without worrying about major formatting changes disrupting their Project.
12+
13+
## Packaging guarantees
14+
15+
Starting with the 5.0.0 release isort includes the following project guarantees to help guide development:
16+
17+
- isort will never have dependencies, optional, required, or otherwise.
18+
- isort will always act the same independent to the Python environment it is installed in.
19+
20+
## Versioning
21+
22+
isort follows the [Semantic Versioning 2.0.0 specification](https://semver.org/spec/v2.0.0.html) meaning it has three numerical version parts with distinct rules
23+
`MAJOR.MINOR.PATCH`.
24+
25+
### Patch Releases x.x.1
26+
27+
Within the isort Project, patch releases are really meant solely to fix bugs and minor oversights.
28+
Patch releases should *never* drastically change formatting, even if it's for the better.
29+
30+
### Minor Releases x.1.x
31+
32+
Minor changes can contain new backward-incompatible features, and of particular note can include bug fixes
33+
that result in intentional formatting changes - but they should still never be too large in scope.
34+
API backward compatibility should strictly be maintained.
35+
36+
### Major Releases 1.x.x
37+
38+
Major releases are the only place where backward-incompatible changes or substantial formatting changes can occur.
39+
Because these kind of changes are likely to break projects that utilize isort, either as a formatter or library,
40+
isort must do the following:
41+
42+
- Release a release candidate with at least 2 weeks for bugs to be reported and fixed.
43+
- Keep releasing follow up release candidates until there are no or few bugs reported.
44+
- Provide an upgrade guide that helps users work around any backward-incompatible changes.
45+
- Provide a detailed changelog of all changes.
46+
- Where possible, warn and point to the upgrade guide instead of breaking when options are removed.

0 commit comments

Comments
 (0)
Please sign in to comment.