Emily Shaffer <emilyshaffer@xxxxxxxxxx> writes:
> +Platform Support Policy
> +=======================
Paraphrasing a bit for my understanding (read: not suggestions to
rewrite), with some comments (read: might suggest rewrites).
> +Git has a history of providing broad "support" for exotic platforms and older
> +platforms, without an explicit commitment.
There currently is no level of guarantees given.
> +This support becomes easier to
> +maintain (and possible to commit to)
We want to give better support and certain levels of guarantees?
(this is left unsaid, though).
If we don't want that, then we would not care what would make
the support easier to maintain, so that's implied. Do we want
to make it more explicit? Perhaps
Stakeholders of such platforms, however, may want to have a more
predictable support commitments. It would require ...
> when Git developers are provided with
> +adequate tooling to test for compatibility.
... platform stakeholders to supply Git developers adequate
tooling to test for compatibility and to develop workarounds for
platform specific quirks, which may be hard to find for such
exotic and/or older platforms without platform stakeholders'
involvement.
> Various levels of tooling will
> +allow us to make more solid commitments around Git's compatibility with your
> +platform.
Good.
All of this document assumes that a working port of Git once existed
in the near past for a platform, and we outline the levels of
investment platform stakeholders can make in order to keep it
working, and expected outcome depending on the level of their
investment. The document does not cover "I now have this exotic
box---could you port Git to it?"
Is it something we want to clarify in this part of the document?
> +Compatible by next release
> +--------------------------
> +
> +To increase probability that compatibility issues introduced in a release
> +will be fixed in a later release:
> +
> +* You should send a bug report as soon as you notice the breakage on your
> +platform. The sooner you notice, the better; watching `seen` means you can
> +notice problems before they are considered "done with review"; whereas watching
> +`master` means the stable branch could break for your platform, but you have a
> +decent chance of avoiding a tagged release breaking you. See "The Policy" in the
> +link:../howto/maintain-git.txt[maintainer's guide] for an overview of which
> +branches are used in git.git, and how.
> +* The bug report should include information about what platform you are using.
> +* You should also use linkgit:git-bisect[1] and determine which commit
> +introduced the breakage.
> +* Please include any information you have about the nature of the breakage: is
> +it a memory alignment issue? Is an underlying library missing or broken for
> +your platform? Is there some quirk about your platform which means typical
> +practices (like malloc) behave strangely?
> +* Once we begin to fix the issue, please work closely with the contributor
> +working on it to test the proposed fix against your platform.
This is a source to be reformatted by AsciiDoc so it _should not_
matter [*], but I find it utterly unreadable if a bulletted list of
paragraphs are formatted like the above.
Side note: ... but it does matter because what we look at while
editing is this .txt source file.
I locally reformatted the above like so:
To increase probability that compatibility issues introduced in a release
will be fixed in a later release:
* You should send a bug report as soon as you notice the breakage on
your platform. The sooner you notice, the better; watching `seen`
means you can notice problems before they are considered "done
with review"; whereas watching `master` means the stable branch
could break for your platform, but you have a decent chance of
avoiding a tagged release breaking you. See "The Policy" in the
link:../howto/maintain-git.txt[maintainer's guide] for an overview
of which branches are used in git.git, and how.
* The bug report should include information about what platform you are using.
* You should also use linkgit:git-bisect[1] and determine which
commit introduced the breakage.
to have the second and subsequent lines indented to begin at the
same column as the first line, and have a blank line between
bulletted list entries, which made it easier to scan the source text.
Such a reformatting did not appear to make any changes when the
resulting HTML file was rendered (via "lynx -dump").
This might be my personal preference, and if other people prefer the
more dense form used inthe patch, then I wouldn't complain.
Regarding this point.
> +* Please include any information you have about the nature of the breakage: is
> +it a memory alignment issue? Is an underlying library missing or broken for
> +your platform? Is there some quirk about your platform which means typical
> +practices (like malloc) behave strangely?
How deep do we expect platform stakeholders to dig in their initial
contact to us? In order to make a firm "It is a memory alignment
issue" would be helped by having otherwise identical version of Git
built from the same source on a more mainstream platform (say,
Debian GNU/Linux running on x86_64) and the exotic platform in
question, to be able to say "Ahh, x86 is lenient to unaligned access
and that is why this problem wasn't noticed by developers, but on my
platform this matters". Is such a comparison something we may want
to hint here? Perhaps at the end of "use git-bisect to find the
exact commit", add something like
Build Git from exactly the same source files on your platform
and one of the mainstream platforms and see if the problem you
noticed appears on both, or only on your platform. If the
former, the suggestions in this document does not apply, but of
course we do greatly appreciate such a bug report that will help
users of every platform.
Note that the above would apply equally for any compatibility
levels, not limited to those who expect "by next release".
> +Example: NonStop
> +https://lore.kernel.org/git/01bd01da681a$b8d70a70$2a851f50$@nexbridge.com/[reports
> +problems] when they're noticed.
> +
> +Compatible on `master` and point releases
> +-----------------------------------------
> +
> +To guarantee that `master` and all point releases work for your platform the
> +first time:
> +
> +* You should run nightly tests against the `next` branch and publish breakage
> +reports to the mailing list immediately when they happen.
> +** You may want to ask to join the mailto:git-security@xxxxxxxxxxxxxxxx[security
> +mailing list] in order to run tests against the fixes proposed there, too.
> +* It may make sense to automate these; if you do, make sure they are not noisy
> +(you don't need to send a report when everything works, only when something
> +breaks).
Also, the same problem that was reported yesterday for yesterday's
'next' does not have to be reported for today's 'next', even if they
are different, as long as the breakage is the same.
> +Compatible on `next`
> +--------------------
> +
> +To guarantee that `next` will work for your platform, avoiding reactive
> +debugging and fixing:
Applies to the phrasing at the beginning of the previous section as
well, but I found it easier to read if you flipped the order from
"do Y and you get X" from "you want X, so do Y", e.g.
We can avoid reactive debugging and fixing, if you make sure
'next' keeps working for your platform.
Do we assume that readers are familiar with the way how `master` and
`next` are used? Otherwise
We can avoid reactive debugging and fixing, if you make sure the
'next' branch keeps working for your platform. The changes in
this branch are what the developers finished reviewing and are
expected to appear in the next tagged release. Unless you stop
them, that is.
> +* You should add a runner for your platform to the GitHub Actions CI suite.
> +This suite is run when any Git developer proposes a new patch, and having a
> +runner for your platform/configuration means every developer will know if they
> +break you, immediately.
I am a bit surprised that nobody from GitLab complained so far, but
the contents of the ci/ hierarchy has been reorganized and it is my
understanding that we now consider both GitLab CI and GitHub Actions
first-class citizens.
> +** If adding it to GitHub Actions is infeasible (due to architecture constraints
> +or for performance reasons), any other method which runs as automatically and
> +quickly as possible works, too. For example, a service which snoops on the
> +mailing list and automatically runs tests on new [PATCH] emails, replying to the
> +author with the results, would also be within the spirit of this requirement.
Again, "do not be too noisy" principle should be stressed, no? If
it breaks only on the exotic platform in question, please do notify,
but if the breakage is shared with all the other platforms, then...?
