Re: [PATCH v2] Documentation: add platform support policy

Emily Shaffer <emilyshaffer@google.com> writes:

Paraphrasing a bit for my understanding (read: not suggestions to rewrite), with some comments (read: might suggest rewrites).

    There currently is no level of guarantees given.

    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 ...

    ... 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.

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?

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.

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".

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.

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.

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.

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...?