launcher: add a requirements framework to declare version dependencies
Currently we don't have a way for the checked out repo version to
declare the version of tools it needs before we start running it.
For somethings, like git, it's not a big deal as it can handle all
the asserts itself. But for things like Python, it's impossible
to reliably check before executing.
We're in this state now:
- we've been allowing Python 3.4, so the launcher accepts it
- the repo codebase starts using Python 3.6 features
- launcher tries to import us but hits syntax errors
- user is left confused and assuming new repo is broken because
they're seeing syntax errors
This scenario is playing out with old launchers that still accept
Python 2, and will continue to play out as time goes on and we want
to require newer versions of Python 3.
Lets create a JSON file to declare all these system requirements.
That file format is extremely stable, so loading & parsing from
even ancient versions of Python shouldn't be a problem. Then the
launcher can read these settings and check the system state before
attempting to execute any code. If the tools are too old, it can
clearly diagnose & display information to the user as to the real
problem (and not emit tracebacks or syntax errors).
We have a couple of different tool version checks already (git,
python, ssh) and can harmonize them in a single place.
This also allows us to assert a reverse dependency if the need
ever comes up: force the user to upgrade their `repo` launcher
before we'll let them run us. Even though the launcher warns
whenever a newer release is available, some users seem to ignore
that, or they don't use repo that often (on the scale of years),
and their upgrade jump is so dramatic that they fall back into
the syntax error pit.
Hopefully by the end of the year we can assume enough people
have upgraded their launcher such that we can delete all of the
duplicate version checks in the codebase. But until then, we'll
keep them to maintain coverage.
Change-Id: I5c12bbffdfd0a8ce978f39aa7f4674026fe9f4f8
Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/293003
Reviewed-by: Michael Mortensen <mmortensen@google.com>
Tested-by: Mike Frysinger <vapier@google.com>
diff --git a/requirements.json b/requirements.json
new file mode 100644
index 0000000..86b9a46
--- /dev/null
+++ b/requirements.json
@@ -0,0 +1,57 @@
+# This file declares various requirements for this version of repo. The
+# launcher script will load it and check the constraints before trying to run
+# us. This avoids issues of the launcher using an old version of Python (e.g.
+# 3.5) while the codebase has moved on to requiring something much newer (e.g.
+# 3.8). If the launcher tried to import us, it would fail with syntax errors.
+
+# This is a JSON file with line-level comments allowed.
+
+# Always keep backwards compatibility in mine. The launcher script is robust
+# against missing values, but when a field is renamed/removed, it means older
+# versions of the launcher script won't be able to enforce the constraint.
+
+# When requiring versions, always use lists as they are easy to parse & compare
+# in Python. Strings would require futher processing to turn into a list.
+
+# Version constraints should be expressed in pairs: soft & hard. Soft versions
+# are when we start warning users that their software too old and we're planning
+# on dropping support for it, so they need to start planning system upgrades.
+# Hard versions are when we refuse to work the tool. Users will be shown an
+# error message before we abort entirely.
+
+# When deciding whether to upgrade a version requirement, check out the distro
+# lists to see who will be impacted:
+# https://gerrit.googlesource.com/git-repo/+/HEAD/docs/release-process.md#Project-References
+
+{
+ # The repo launcher itself. This allows us to force people to upgrade as some
+ # ignore the warnings about it being out of date, or install ancient versions
+ # to start with for whatever reason.
+ #
+ # NB: Repo launchers started checking this file with repo-2.12, so listing
+ # versions older than that won't make a difference.
+ "repo": {
+ "hard": [2, 11],
+ "soft": [2, 11]
+ },
+
+ # Supported Python versions.
+ #
+ # python-3.6 is in Ubuntu Bionic.
+ # python-3.5 is in Debian Stretch.
+ "python": {
+ "hard": [3, 5],
+ "soft": [3, 6]
+ },
+
+ # Supported git versions.
+ #
+ # git-1.7.2 is in Debian Squeeze.
+ # git-1.7.9 is in Ubuntu Precise.
+ # git-1.9.1 is in Ubuntu Trusty.
+ # git-1.7.10 is in Debian Wheezy.
+ "git": {
+ "hard": [1, 7, 2],
+ "soft": [1, 9, 1]
+ }
+}