You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Our policy for merging and reviewing describes how we review one another's work, and when we allow others to merge changes into our main codebase.
6
4
It tries to balance between a few goals:
@@ -18,7 +16,7 @@ We follow these guidelines in order to achieve these goals:
18
16
- It's important to share information, so give a best effort at telling others about work that you're doing.
19
17
- It's best to discuss and agree on important decisions at a high level before implementation, so give a best effort at providing time and invitation for others to provide feedback.
20
18
21
-
###Policy for moderate changes
19
+
## Policy for moderate changes
22
20
23
21
These are changes that make modest changes to new or existing functionality, but that aren't going to significantly change the default behavior of the theme, user configuration, etc.
24
22
This is the majority of changes that we make.
@@ -33,38 +31,16 @@ They can be merged when the above conditions are met, and one of these things ha
33
31
- The PR has at least one approval from a core maintainer that isn't the PR author
34
32
- The PR author has signaled their intent to merge unless there are objections, and 48 hours have passed since that comment.
35
33
36
-
###Policy for major new features and breaking changes
34
+
## Policy for major new features and breaking changes
37
35
38
36
These are changes that significantly alter the experience of the user, or that add significant complexity to the codebase.
39
37
40
38
All of the above, but PRs **must** have approval from at least one other core maintainer before merging.
41
39
In addition, the PR author should put extra effort into ensuring that the relevant stakeholders are notified about a change, so they can gauge its impact and provide feedback.
42
40
43
-
###Policy For minor changes and bugfixes
41
+
## Policy For minor changes and bugfixes
44
42
45
43
These are small changes that might be noticeable to the user, but in a way that is clearly an improvement.
46
44
They generally shouldn't touch too many lines of code.
47
45
48
46
Update the relevant tests and documentation, but PR authors are welcome to self-merge whenever they like without PR approval.
49
-
50
-
(policies:release)=
51
-
52
-
## Release policy
53
-
54
-
Our release policy describes how we decide when to make a new public release of the theme so that other projects may use new features and improvements.
55
-
It tries to balance between these goals:
56
-
57
-
- Release relatively frequently, so that we provide a continuous stream of improvement to projects that use the theme, and minimize the effort needed to upgrade.
58
-
- Do not surprise people (especially with negative surprises) and provide time for projects to provide feedback about upcoming features.
59
-
- Minimize the toil and complexity associated with releases, and reduce information silos and bottlenecks associated with them.
60
-
61
-
### Release policy guidelines
62
-
63
-
Here are the guidelines we follow when creating new releases:
64
-
65
-
- Encourage releases whenever a maintainer feels there has been a "significant" change in the codebase. The bar for this should be relatively low.
66
-
- Releases should be as automated as possible, and should not rely on a single person to have special permissions or credentails.
67
-
- Use the [{guilabel}`block-release`](https://github.com/pydata/pydata-sphinx-theme/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Ablock-release) label to prevent a release from happening until an issue is resolved.
68
-
- Use [GitHub Milestones](https://github.com/pydata/pydata-sphinx-theme/milestones) to organize the issues that should be resolved as part of a new release.
69
-
- For non-trivial changes, **make a `release candidate`** and ask for feedback from users. This is important because we do not test much of the CSS and JavaScript-based functionality in our testing infrastructure.
70
-
- After a week or so, if there are no blocking issues that have been opened since the Release Candidate, we can make a full release.
Our release policy describes how we decide when to make a new public release of the theme so that other projects may use new features and improvements.
8
+
It tries to balance between these goals:
9
+
10
+
- Release relatively frequently, so that we provide a continuous stream of improvement to projects that use the theme, and minimize the effort needed to upgrade.
11
+
- Do not surprise people (especially with negative surprises) and provide time for projects to provide feedback about upcoming features.
12
+
- Minimize the toil and complexity associated with releases, and reduce information silos and bottlenecks associated with them.
13
+
14
+
(releases:when)=
15
+
16
+
## When to make a release
17
+
18
+
Anybody is encouraged to make a new release if:
19
+
20
+
- It has been more than a month since the last release.
21
+
- OR a significant change has been made to our code that warrants a release.
22
+
- AND there are no open issues with a [{guilabel}`block-release`](https://github.com/pydata/pydata-sphinx-theme/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Ablock-release) label.
23
+
24
+
### Release candidates
25
+
26
+
If a release includes complex or many changes (especially in JavaScript), make a `release candidate` and ask for feedback from users.
27
+
This is important because we do not test much of the CSS and JavaScript-based functionality in our testing infrastructure.
28
+
After a week or so, if there are no blocking issues that have been opened since the Release Candidate, we can make a full release.
29
+
30
+
## Process for making a release
31
+
32
+
This theme uses GitHub tags and releases to automatically push new releases to
33
+
PyPI.
34
+
Follow these steps to make a release:
35
+
36
+
- (optionally) **Create a [GitHub milestones](https://github.com/pydata/pydata-sphinx-theme/milestones)** to organize the issues that should be resolved as part of a new release.
37
+
-**Decide if it's time** to make a release be reading [](releases:when) and decide if it is time for a release.
38
+
-**Copy the release checklist into a new issue**. We have [a release checklist in our wiki](https://github.com/pydata/pydata-sphinx-theme/wiki/Release-checklist#release-instructions).
39
+
-**Complete the checklist**. That's it!
40
+
41
+
## Choosing a version increment
42
+
43
+
We use [semantic versioning](https://semver.org/) to decide whether it's a major, minor, or patch bump. Before we have released `1.0`, treat minor versions as breaking releases, and patch versions as feature / patch releases. **If this is a release candidate**, tag it like `0.1rc1`.
Python and Sphinx are the two primary dependencies of this theme.
4
+
We have special practices for deciding which versions of these we support (especially Sphinx, which tends to release breaking changes).
5
+
6
+
## Supported Python versions
7
+
8
+
For releases of Python, we aim to follow this approach[^1]:
9
+
10
+
> For a new major/minor release of this theme, we support any minor Python versions released in the last 3.5 years (42 months), as defined in [the EOL schedule for Python](https://endoflife.date/python)[^2].
11
+
12
+
We define "support" as testing against each of these versions, so that users can be assured they will not trigger any bugs.
13
+
14
+
For example, if we made a minor release tomorrow, we'd [look at the EOL schedule for Python](https://endoflife.date/python) and support all of the versions that fall within a 3.5 year window.
15
+
16
+
[^1]: Our support for Python versions is inspired by [NEP 029](https://numpy.org/neps/nep-0029-deprecation_policy.html).
17
+
[^2]: These policies are goals, but not promises. We are a volunteer-led community with limited time. Consider these sections to be our intention, but we recognize that we may not always be able to meet these criteria if we do not have capacity to do so. We welcome contributions from others to help us more sustainably meet these goals!
18
+
19
+
## Supported Sphinx versions
20
+
21
+
For supporting versions of Sphinx, we aim to follow this approach:
22
+
23
+
> We support the latest released version of Sphinx that is **older than 6 months**.
24
+
> We unofficially support earlier released versions of Sphinx, but may increase the lower-bound in our dependency pin without warning if needed[^2].
25
+
26
+
When a new pre-release of Sphinx is released, we should follow these steps:
27
+
28
+
- Ensure that our tests are passing. We run our tests with any **pre-releases** of Sphinx, so we can test major errors quickly and make the necessary changes.
29
+
-[Look at the Sphinx Changelog](https://www.sphinx-doc.org/en/master/changes.html) and make sure there are no changes that might break things that aren't captured by our tests.
30
+
-[Look at the deprecated API changes](https://www.sphinx-doc.org/en/master/extdev/deprecated.html) and make sure there are no changes that might break things that aren't captured by our tests.
31
+
-[Look at the docutils changelog](https://docutils.sourceforge.io/RELEASE-NOTES.html) in case there's a new docutils version supported that breaks something.
32
+
33
+
```{note}
34
+
This theme does not pin the upper version of Sphinx that it supports.
35
+
If a Sphinx release causes major breaking changes for our users, and we do not have the capacity to update our code and release a fix, we may temporarily pin the upper bound of Sphinx we support until this is fixed.
0 commit comments