diff --git a/.github/workflows/no-response.yml b/.github/workflows/no-response.yml index afaae8ed..9f62c14e 100644 --- a/.github/workflows/no-response.yml +++ b/.github/workflows/no-response.yml @@ -1,26 +1,26 @@ -name: No Response - -# Both `issue_comment` and `scheduled` event types are required for this Action -# to work properly. -on: - issue_comment: - types: [created] - schedule: - # Schedule for ten minutes after the hour, every hour - - cron: '10 * * * *' - -jobs: - noResponse: - runs-on: ubuntu-latest - steps: - - uses: lee-dohm/no-response@v0.5.0 - with: - token: ${{ github.token }} - daysUntilClose: 30 - responseRequiredLabel: need-feedback - closeComment: > - This issue has been automatically closed because there has been no response - to our request for more information from the original author. With only the - information that is currently in the issue, we don't have enough information - to take action. Please reach out if you have or find the answers we need so - that we can investigate further. +name: No Response + +# Both `issue_comment` and `scheduled` event types are required for this Action +# to work properly. +on: + issue_comment: + types: [created] + schedule: + # Schedule for ten minutes after the hour, every hour + - cron: '10 * * * *' + +jobs: + noResponse: + runs-on: ubuntu-latest + steps: + - uses: lee-dohm/no-response@v0.5.0 + with: + token: ${{ github.token }} + daysUntilClose: 30 + responseRequiredLabel: need-feedback + closeComment: > + This issue has been automatically closed because there has been no response + to our request for more information from the original author. With only the + information that is currently in the issue, we don't have enough information + to take action. Please reach out if you have or find the answers we need so + that we can investigate further. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 24b1ce61..3f59ee03 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,109 +1,109 @@ -General guidance -================ - -* The usual principles of respecting existing conventions and making sure that your changes - are in line with the overall product design apply when contributing code to Pyenv. - -* We are limited to Bash 3.2 features - - That's because that's the version shipped with MacOS. - (They didn't upgrade past it and switched to Zsh because later versions - are covered by GPLv3 which has additional restrictions unacceptable for Apple.) - - You can still add performance optimizations etc that take advantage of newer Bash features - as long as there is a fallback execution route for Bash 3. - -* Be extra careful when submitting logic specific for the Apple Silicon platform - - As of this writing, Github Actions do not support it and only one team member has the necessary hardware. - So we may be unable to test your changes and may have to take your word for it. - - -Formatting PRs -============== - -We strive to keep commit history one-concern-per-commit to keep it meaningful and easy to follow. -If a pull request (PR) addresses a single concern (the typical case), we usually squash commits -from it together when merging so its commit history doesn't matter. -If however a PR addresses multiple separate concerns, each of them should be presented as a separate commit. -Adding multiple new Python releases of the same flavor is okay with either a single or multiple commits. - - -Authoring installation scripts -============================== - -Adding new Python release support ---------------------------------- - -The easiest way to add support for a new Python release is to copy the script from the previous one -and adjust it as necessary. In many cases, just changing version numbers, URLs and hashes is enough. -Do pay attention to other "magic numbers" that may be present in a script -- -e.g. the set of architectures and OS versions supported by a release -- since those change from time to time, too. - -Make sure to also copy any patches for the previous release that still apply to the new one. -Typically, a patch no longer applies if it addresses a problem that's already fixed in the new release. - -For prereleases, we only create an entry for the latest prerelease in a specific version line. -When submitting a newer prerelease, replace the older one. - - -Adding version-specific fixes/patches -------------------------------------- - -We accept fixes to issues in specific Python releases that prevent users from using them with Pyenv. - -In the default configuration for a Python release, we strive to provide as close to vanilla experience as practical, -to maintain [the principle of the least surprise](https://en.wikipedia.org/wiki/Principle_of_least_astonishment). -As such, any such fixes: - -* Must not break or degrade (e.g. disable features) the build in any of the environments that the release officially supports -* Must not introduce incompatibilities with the vanilla release (including binary incompatibilities) -* Should not patch things unnecessarily, to minimize the risk of the aforementioned undesirable side effects. - * E.g. if the fix is for a specific environment, its logic ought to only fire in this specific environment and not touch execution paths for other environments. - * As such, it's advisable to briefly explain in the PR what each added patch does and why it is necessary to fix the declared problem - -Generally, version-specific fixes belong in the scripts for the affected releases and/or patches for them -- this guarantees that their effect is limited to only those releases. - -

Backporting upstream patches

- -Usually, this is the easiest way to backport a fix for a problem that is fixed in a newer release. - -* Clone Python, check out the tag for the appropriate release and create a branch -* Apply existing patches if there are any (with either `patch` or `git am`) and commit -* Cherry-pick the upstream commit that fixes the problem in a newer release -* Commit and `git format-patch` -* Commit the generated patch file into Pyenv, test your changes and submit a PR - - -Deprecation policy ------------------- - -We do not provide official support for EOL releases and environments or otherwise provide any kind of extended support for old Python releases. - -We do however accept fixes from interested parties that would allow running older, including EOL, releases in newer environments. -In addition to the above requirements for release-specific fixes, - -* Such a fix must not add maintenance burden (e.g. add new logic to `python-build` that has to be kept there indefinitely) - * Unless the added logic is useful for both EOL and non-EOL releases. In this case, it will be considered as being primarily an improvement for non-EOL releases. -* Support is provided on a "best effort" basis: we do not maintain these fixes but won't actively break them, either, and accept any corrections. - Since old releases never change, it's pretty safe to assume that the fixes will continue to work until a later version - of an environment introduces further incompatible changes. - - -Advanced changes / adding new Python flavor support ---------------------------------------------------- - -An installation script is sourced from `python-build`. All installation scripts are based on the same logic: - -1. Select the source to download and other variable parameters as needed. - - This includes showing an error if the user's environment (OS, architecture) is not supported by the release. - Binary releases that only officially support specific distro(s) typically show a warning in other distros instead. - -2. Run one of the `install_*` shell functions - -`install_*` shell functions defined in `python-build` install Python from different kinds of sources -- compressed package (binary or source), upstream installation script, VCS checkout. Pick one that's the most appropriate for your packaging. - -Each of them accepts a couple of function-specific arguments which are followed by arguments that constitute the build sequence. Each `` in the build sequence corresponds to the `install_*_` function in `python-build`. Check what's available and add any functions with logic specific to your flavor if needed. - -We strive to keep out of `python-build` parts of build logic that are release-specific and/or tend to change abruptly between releases -- e.g. sets of supported architectures and other software's versions. This results in logic duplication between installation scripts -- but since old releases never change once released, this doesn't really add to the maintenance burden. As a rule of thumb, `python-build` can host parts of logic that are expected to stay the same for an indefinite amount of time -- for an entire Python flavor or release line. +General guidance +================ + +* The usual principles of respecting existing conventions and making sure that your changes + are in line with the overall product design apply when contributing code to Pyenv. + +* We are limited to Bash 3.2 features + + That's because that's the version shipped with MacOS. + (They didn't upgrade past it and switched to Zsh because later versions + are covered by GPLv3 which has additional restrictions unacceptable for Apple.) + + You can still add performance optimizations etc that take advantage of newer Bash features + as long as there is a fallback execution route for Bash 3. + +* Be extra careful when submitting logic specific for the Apple Silicon platform + + As of this writing, Github Actions do not support it and only one team member has the necessary hardware. + So we may be unable to test your changes and may have to take your word for it. + + +Formatting PRs +============== + +We strive to keep commit history one-concern-per-commit to keep it meaningful and easy to follow. +If a pull request (PR) addresses a single concern (the typical case), we usually squash commits +from it together when merging so its commit history doesn't matter. +If however a PR addresses multiple separate concerns, each of them should be presented as a separate commit. +Adding multiple new Python releases of the same flavor is okay with either a single or multiple commits. + + +Authoring installation scripts +============================== + +Adding new Python release support +--------------------------------- + +The easiest way to add support for a new Python release is to copy the script from the previous one +and adjust it as necessary. In many cases, just changing version numbers, URLs and hashes is enough. +Do pay attention to other "magic numbers" that may be present in a script -- +e.g. the set of architectures and OS versions supported by a release -- since those change from time to time, too. + +Make sure to also copy any patches for the previous release that still apply to the new one. +Typically, a patch no longer applies if it addresses a problem that's already fixed in the new release. + +For prereleases, we only create an entry for the latest prerelease in a specific version line. +When submitting a newer prerelease, replace the older one. + + +Adding version-specific fixes/patches +------------------------------------- + +We accept fixes to issues in specific Python releases that prevent users from using them with Pyenv. + +In the default configuration for a Python release, we strive to provide as close to vanilla experience as practical, +to maintain [the principle of the least surprise](https://en.wikipedia.org/wiki/Principle_of_least_astonishment). +As such, any such fixes: + +* Must not break or degrade (e.g. disable features) the build in any of the environments that the release officially supports +* Must not introduce incompatibilities with the vanilla release (including binary incompatibilities) +* Should not patch things unnecessarily, to minimize the risk of the aforementioned undesirable side effects. + * E.g. if the fix is for a specific environment, its logic ought to only fire in this specific environment and not touch execution paths for other environments. + * As such, it's advisable to briefly explain in the PR what each added patch does and why it is necessary to fix the declared problem + +Generally, version-specific fixes belong in the scripts for the affected releases and/or patches for them -- this guarantees that their effect is limited to only those releases. + +

Backporting upstream patches

+ +Usually, this is the easiest way to backport a fix for a problem that is fixed in a newer release. + +* Clone Python, check out the tag for the appropriate release and create a branch +* Apply existing patches if there are any (with either `patch` or `git am`) and commit +* Cherry-pick the upstream commit that fixes the problem in a newer release +* Commit and `git format-patch` +* Commit the generated patch file into Pyenv, test your changes and submit a PR + + +Deprecation policy +------------------ + +We do not provide official support for EOL releases and environments or otherwise provide any kind of extended support for old Python releases. + +We do however accept fixes from interested parties that would allow running older, including EOL, releases in newer environments. +In addition to the above requirements for release-specific fixes, + +* Such a fix must not add maintenance burden (e.g. add new logic to `python-build` that has to be kept there indefinitely) + * Unless the added logic is useful for both EOL and non-EOL releases. In this case, it will be considered as being primarily an improvement for non-EOL releases. +* Support is provided on a "best effort" basis: we do not maintain these fixes but won't actively break them, either, and accept any corrections. + Since old releases never change, it's pretty safe to assume that the fixes will continue to work until a later version + of an environment introduces further incompatible changes. + + +Advanced changes / adding new Python flavor support +--------------------------------------------------- + +An installation script is sourced from `python-build`. All installation scripts are based on the same logic: + +1. Select the source to download and other variable parameters as needed. + + This includes showing an error if the user's environment (OS, architecture) is not supported by the release. + Binary releases that only officially support specific distro(s) typically show a warning in other distros instead. + +2. Run one of the `install_*` shell functions + +`install_*` shell functions defined in `python-build` install Python from different kinds of sources -- compressed package (binary or source), upstream installation script, VCS checkout. Pick one that's the most appropriate for your packaging. + +Each of them accepts a couple of function-specific arguments which are followed by arguments that constitute the build sequence. Each `` in the build sequence corresponds to the `install_*_` function in `python-build`. Check what's available and add any functions with logic specific to your flavor if needed. + +We strive to keep out of `python-build` parts of build logic that are release-specific and/or tend to change abruptly between releases -- e.g. sets of supported architectures and other software's versions. This results in logic duplication between installation scripts -- but since old releases never change once released, this doesn't really add to the maintenance burden. As a rule of thumb, `python-build` can host parts of logic that are expected to stay the same for an indefinite amount of time -- for an entire Python flavor or release line.