Add CodingGuidelines & friends to docs/
#1965
Conversation
There are a couple of "manual pages" that are really not interesting to regular Git users because they affect how to work _with the Git project_, not how to work _with Git_. It is somewhat unfortunate (and a clear lack of separation of concerns) that these are included in what Git's home page calls the "Git reference". Note that this has not been the case for a long time! Only with ea0e16d (docs: include SubmittingPatches, 2018-04-16) it changed, adding a single Git project-specific file to the site. Since that dam was broken, 44bf766 (index.rake: build MyFirstContribution tutorial, 2019-08-14) and later db4e920 (docs: render 'MyFirstObjectWalk', 2020-06-07) introduced _further_ pages that have nothing to do, really, with how to use Git. In preparation for labeling these pages clearly as specific to the Git project, let's extract the list of these _special_ pages to a central location where it can be reused in the Hugo part of the site generation. Signed-off-by: Johannes Schindelin <[email protected]>
This makes it more convenient to link to, say, the part talking about contributing to Git. Signed-off-by: Johannes Schindelin <[email protected]>
This adds a callout at the top of the pages that are irrelevant to all Git users except the ones who wish to contribute to the Git project itself. There are only very few of them, anyway (about to be a few more), but it is a good idea to ensure that readers are not confused into believing that they have to follow the Git project's coding guidelines if they want to use Git. Signed-off-by: Johannes Schindelin <[email protected]>
Now that they are clearly labeled as such, let's augment the list of "manual pages" that concern themselves with information only relevant for contributors to the Git project itself. This closes git#1938, git#1939 and git#1961. Signed-off-by: Johannes Schindelin <[email protected]>
Updated via the `update-git-version-and-manual-pages.yml` GitHub workflow.
Only so-called "shortcodes" are supported as Hugo constructs in the `content/` pages. I had forgottent that when I wrote 1deace4 (docs: include more Git project-specific pages, 2025-03-01). Thankfully, the `ci` build pointed it out (specifically, the link checker step). Normally, I would now squash the fix into the offending commit, but there have been automated changes in the meantime (which took a bit over a quarter hour to run) and in the interest of some convenience for myself (and to be able to go relax instead of pouring more time into this topic branch than I already have), and of keeping the original commits as made by the automated workflow run, I will just leave this fix on top of the automated changes. Signed-off-by: Johannes Schindelin <[email protected]>
FWIW this problem is about to be solved. Git 2.49 renames doc files to *.adoc so GitHub renders them nicely and you can link to sections |
@hickford Please note that this "solution" comes at a high price: #1944 will take some serious work to unbreak https://git-scm.com/docs/, and so far nobody has volunteered. And in keeping with the fine tradition of half-solutions, |
Also, I am sure that this will cause its fair share of fine fall-out over at https://github.com/jnavila/git-manpages-l10n and at https://github.com/jnavila/git-html-l10n, right @jnavila? It's quite the gift. |
By the way, before this important point gets lost in the chatter: The fact that upstream was willing to bulk-rename those files (and thereby risk tons of now-broken links to, say, https://github.com/git/git/blob/HEAD/Documentation/git.txt, should give you pause: A deed once done is more likely to be repeated. That is, I have less faith in the longevity of https://github.com/git/git/blob/HEAD/Documentation/git.adoc than I had in the longevity of https://github.com/git/git/blob/HEAD/Documentation/git.txt (and my skepticism about the latter was proven correct). |
|
Including these files in the site is not bad per se. Similar content is usually available in dedicated "Developers" or "Community" sections for other open source projects. Also, being separated from the user's documentation, they are not supposed to be translated (we expect any contributor to understand and write a minimum English). I'm not planning to add these files to corpus of translation. Personally, this has also been a reference I pointed colleagues or friends to when giving advice and example of sensibly well maintained projects. |
|
One thing to notice though: At least for the coding guidelines, I did not write the section on documentation with asciidoc in mind. So the structure of this section does not comply with Asciidoc, and most of the markups are not escaped, leading to a mess in the rendering. This statement is also applicable to other sections. I haven't seen any patches to correct this, so I guess it's down to me. |
|
@jnavila CodingGuidelines, and its choice of mark-up (or lack thereof) isn't your fault, it's mine: git/git@6d0618a. And no, I don't agree it's down to you, unless this really irks you. |
|
@dscho Great work! All looks good to me. I've noticed
But that's not new to this PR, so we should be addressing that separately. |
Thank you!
Agreed. |
Changes
This PR adds a banner to the top of the pages in the Git reference section which are actually not manual pages how to use Git at all but are very, very specific to the Git project itself and hence interesting merely to contributors of said project.
It then goes on and adds a couple more of those pages, by popular demand: #1938, #1939, #1961.
You can see the proposed changes in action here:
Context
It is a somewhat lamentable fact that https://git-scm.com/docs/ not only contains the manual pages that are relevant to Git users (of which there are millions), but since ea0e16d also added pages that are totally uninteresting to the vast majority of Git users, as they contain information pertaining to the Git project itself, i.e. the intended audience of those pages are Git contributors (of which there aren't millions).
Nevertheless, there are reasons to keep those in place, not the least important of which being Hyrum's Law.
But there is also the convenience of having a stable permalink to sections such as https://git-scm.com/docs/SubmittingPatches#dco (something that cannot be done with Git's principal repository at git://git.kernel.org/pub/scm/git/git.git/, and not even with the 3rd-level fall-back repository on GitHub (https://github.com/git/git/blob/v2.48.1/Documentation/SubmittingPatches#L351 is close, granted, but anchors at a specific line number instead of a specific header and is hence inherently stuck with a specific Git version whose information may easily get stale over time).
So I am giving up on maintaining proper boundaries and am even adding three more such pages.
To alleviate this non-separation of concerns at least somewhat, I also added banners to the top of these pages:
Granted, many readers may miss this, but hey, it's the best I could come up with.
The first few four commits are the actual heart of this PR, the fifth commit was made by the
update-git-version-and-manual-pagesworkflow run that I triggered manually, forcing a rebuild of all the Git versions' manual pages.The manually-triggered
update-translated-manual-pagesworkflow run (also forcing a complete rebuild) resulted in no changes, which is as intended, as the Git project demands contributors to communicate in English (which relieves me of the headache of providing translated versions of the banner that I introduced).This closes #1938, #1939 and #1961.