mirror of
https://gerrit.googlesource.com/git-repo
synced 2024-12-21 07:16:21 +00:00
python-support: update with current status & guidelines
This doc was written back in 2019 when we were planning on the Python 3 migration. It isn't relevant anymore, and people are reading it thinking we still support Python 2. Rewrite it to match current requirements and to make it clear there is no support for older versions. Bug: 302871152 Change-Id: I2acf3aee1816a03ee0a70774db8bf4a23713a03f Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/389455 Commit-Queue: Mike Frysinger <vapier@google.com> Reviewed-by: Aravind Vasudevan <aravindvasudev@google.com> Tested-by: Mike Frysinger <vapier@google.com>
This commit is contained in:
Mike Frysinger
LUCI
parent
3b8f9535c7
commit
1544afe460
@ -1,47 +1,93 @@
|
|||||||
# Supported Python Versions
|
# Supported Python Versions
|
||||||
|
|
||||||
With Python 2.7 officially going EOL on [01 Jan 2020](https://pythonclock.org/),
|
This documents the current supported Python versions, and tries to provide
|
||||||
we need a support plan for the repo project itself.
|
guidance for when we decide to drop support for older versions.
|
||||||
Inevitably, there will be a long tail of users who still want to use Python 2 on
|
|
||||||
their old LTS/corp systems and have little power to change the system.
|
|
||||||
|
|
||||||
## Summary
|
## Summary
|
||||||
|
|
||||||
* Python 3.6 (released Dec 2016) is required by default starting with repo-2.x.
|
* Python 3.6 (released Dec 2016) is required starting with repo-2.0.
|
||||||
* Older versions of Python (e.g. v2.7) may use the legacy feature-frozen branch
|
* Older versions of Python (e.g. v2.7) may use old releases via the repo-1.x
|
||||||
based on repo-1.x.
|
branch, but no support is provided.
|
||||||
|
|
||||||
## Overview
|
## repo hooks
|
||||||
|
|
||||||
We provide a branch for Python 2 users that is feature-frozen.
|
|
||||||
Bugfixes may be added on a best-effort basis or from the community, but largely
|
|
||||||
no new features will be added, nor is support guaranteed.
|
|
||||||
|
|
||||||
Users can select this during `repo init` time via the [repo launcher].
|
|
||||||
Otherwise the default branches (e.g. stable & main) will be used which will
|
|
||||||
require Python 3.
|
|
||||||
|
|
||||||
This means the [repo launcher] needs to support both Python 2 & Python 3, but
|
|
||||||
since it doesn't import any other repo code, this shouldn't be too problematic.
|
|
||||||
|
|
||||||
The main branch will require Python 3.6 at a minimum.
|
|
||||||
If the system has an older version of Python 3, then users will have to select
|
|
||||||
the legacy Python 2 branch instead.
|
|
||||||
|
|
||||||
### repo hooks
|
|
||||||
|
|
||||||
Projects that use [repo hooks] run on independent schedules.
|
Projects that use [repo hooks] run on independent schedules.
|
||||||
They might migrate to Python 3 earlier or later than us.
|
Since it's not possible to detect what version of Python the hooks were written
|
||||||
To support them, we'll probe the shebang of the hook script and if we find an
|
or tested against, we always import & exec them with the active Python version.
|
||||||
interpreter in there that indicates a different version than repo is currently
|
|
||||||
running under, we'll attempt to reexec ourselves under that.
|
|
||||||
|
|
||||||
For example, a hook with a header like `#!/usr/bin/python2` will have repo
|
If the user's Python is too new for the [repo hooks], then it is up to the hooks
|
||||||
execute `/usr/bin/python2` to execute the hook code specifically if repo is
|
maintainer to update.
|
||||||
currently running Python 3.
|
|
||||||
|
|
||||||
For more details, consult the [repo hooks] documentation.
|
## Repo launcher
|
||||||
|
|
||||||
|
The [repo launcher] is an independent script that can support older versions of
|
||||||
|
Python without holding back the rest of the codebase.
|
||||||
|
If it detects the current version of Python is too old, it will try to reexec
|
||||||
|
via a newer version of Python via standard `pythonX.Y` interpreter names.
|
||||||
|
|
||||||
|
However, this is provided as a nicety when it is not onerous, and there is no
|
||||||
|
official support for older versions of Python than the rest of the codebase.
|
||||||
|
|
||||||
|
If your default python interpreters are too old to run the launcher even though
|
||||||
|
you have newer versions installed, your choices are:
|
||||||
|
|
||||||
|
* Modify the [repo launcher]'s shebang to suite your environment.
|
||||||
|
* Download an older version of the [repo launcher] and don't upgrade it.
|
||||||
|
Be aware that there is no guarantee old repo launchers are WILL work with
|
||||||
|
current versions of repo. Bug reports using old launchers will not be
|
||||||
|
accepted.
|
||||||
|
|
||||||
|
## When to drop support
|
||||||
|
|
||||||
|
So far, Python 3.6 has provided most of the interesting features that we want
|
||||||
|
(e.g. typing & f-strings), and there haven't been features in newer versions
|
||||||
|
that are critical to us.
|
||||||
|
|
||||||
|
That said, let's assume we need functionality that only exists in Python 3.7.
|
||||||
|
How do we decide when it's acceptable to drop Python 3.6?
|
||||||
|
|
||||||
|
1. Review the [Project References](./release-process.md#project-references) to
|
||||||
|
see what major distros are using the previous version of Python, and when
|
||||||
|
they go EOL. Generally we care about Ubuntu LTS & current/previous Debian
|
||||||
|
stable versions.
|
||||||
|
* If they're all EOL already, then go for it, drop support.
|
||||||
|
* If they aren't EOL, start a thread on [repo-discuss] to see how the user
|
||||||
|
base feels about the proposal.
|
||||||
|
1. Update the "soft" versions in the codebase. This will start warning users
|
||||||
|
that the older version is deprecated.
|
||||||
|
* Update [repo](/repo) if the launcher needs updating.
|
||||||
|
This only helps with people who download newer launchers.
|
||||||
|
* Update [main.py](/main.py) for the main codebase.
|
||||||
|
This warns for everyone regardless of [repo launcher] version.
|
||||||
|
* Update [requirements.json](/requirements.json).
|
||||||
|
This allows [repo launcher] to display warnings/errors without having
|
||||||
|
to execute the new codebase. This helps in case of syntax or module
|
||||||
|
changes where older versions won't even be able to import the new code.
|
||||||
|
1. After some grace period (ideally at least 2 quarters after the first release
|
||||||
|
with the updated soft requirements), update the "hard" versions, and then
|
||||||
|
start using the new functionality.
|
||||||
|
|
||||||
|
## Python 2.7 & 3.0-3.5
|
||||||
|
|
||||||
|
> **There is no support for these versions.**
|
||||||
|
> **Do not file bugs if you are using old Python versions.**
|
||||||
|
> **Any such reports will be marked invalid and ignored.**
|
||||||
|
> **Upgrade your distro and/or runtime instead.**
|
||||||
|
|
||||||
|
Fetch an old version of the [repo launcher]:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
$ curl https://storage.googleapis.com/git-repo-downloads/repo-2.32 > ~/.bin/repo-2.32
|
||||||
|
$ chmod a+rx ~/.bin/repo-2.32
|
||||||
|
```
|
||||||
|
|
||||||
|
Then initialize an old version of repo:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
$ repo-2.32 init --repo-rev=repo-1 ...
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
[repo-discuss]: https://groups.google.com/forum/#!forum/repo-discuss
|
||||||
[repo hooks]: ./repo-hooks.md
|
[repo hooks]: ./repo-hooks.md
|
||||||
[repo launcher]: ../repo
|
[repo launcher]: ../repo
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user