Move release guide from website to new contributor-docs/ home

[kennknowles]

Following discussion at https://lists.apache.org/thread/8rsqk2sbd0vqjfs8696z0nm0r6q9xyn0 starting a new contributor-docs/ folder with the release guide.

I will bring other pieces of the Wiki and other docs in as I go. This is just a start to get the guide moved with nearly zero changes. The only changes I made were to migrate to GitHub-flavored markdown and make it readable as plain text so it is not dependent on a renderer.

---

Thank you for your contribution! Follow this checklist to help us incorporate your contribution quickly and easily:

• Mention the appropriate issue in your description (for example: addresses #123), if applicable. This will automatically add a link to the pull request in the issue. If you would like the issue to automatically close on merging the pull request, comment fixes #<ISSUE NUMBER> instead.
• Update CHANGES.md with noteworthy changes.
• If this contribution is large, please file an Apache Individual Contributor License Agreement.

See the Contributor Guide for more tips on how to make review process smoother.

To check the build health, please visit https://github.com/apache/beam/blob/master/.test-infra/BUILD_STATUS.md

GitHub Actions Tests Status (on master branch)

See CI.md for more information about GitHub Actions CI or the workflows README to see a list of phrases to trigger workflows.

[kennknowles]

R: @lostluck
CC: @damccorm @robertwb

[github-actions]

Stopping reviewer notifications for this pull request: review requested by someone other than the bot, ceding control

[damccorm]

I actually think that losing this is a big downside. Could we add one that manually links to the sections? Obviously not as ideal as one that automatically stays up to date, but still probably very helpful

[kennknowles]

It can be added automatically, but it is automatically generated by GitHub: https://github.blog/changelog/2021-04-13-table-of-contents-support-in-markdown-files/

Do you also want it inline?

[kennknowles]

Demo via https://github.com/apache/beam/blob/2af1a367b6797819be77391a3173797d6da4ab03/contributor-docs/release-guide.md

[damccorm]

Oh interesting, I have never noticed this feature. I expect others haven't either, but its probably fine? Up to you I guess.

[kennknowles]

BTW I somehow thought there was a [TOC] thing we could add here to get both, which I'd be fine with, but I couldn't find it.

[damccorm]

AFAIK there isn't, but I also didn't know about the other version of TOC that you pointed out.

[damccorm]

Nit: I don't really like this change; using 1. for everything leads to the same result and makes it easier to insert or remove things later with a minimal diff

[kennknowles]

Strong disagree. Using 1 for everything makes the file unreadable without a renderer, and relegates markdown to only a source language, whereas it was (rightly) invented to be a standard way of writing text that could optionally be rendered. My nit: the hack to just use 1. should never have been done in any file on the whole internet :-)

[lostluck]

I'm with Kenn on this one. Minimizing diffs in this context is the wrong priority.

[damccorm]

Minimizing diffs is part of it, but also you're less likely to accidentally get things wrong.

Using 1 for everything makes the file unreadable without a renderer

Is it really unreadable? If you're doing a lot of referencing like after step #1 do X, then maybe, but the intent of ordering is still there.

With all that said, I'm not super interested in getting into an opinion-driven argument here and will certainly not block on this.

[damccorm]

I will also at least point out that I consulted 4 different markdown style guides and all recommended numbering for long lists (which would include this one) if you don't have a formatting tool that takes care of fixing numbers automatically. Some recommended it for short lists too (e.g. https://cirosantilli.com/markdown-style-guide/#ordered). Again, that just means that others have my opinion (not that its correct) and the tradeoff here is somewhat obvious.

[kennknowles]

I think the main axiom that is opinion-driven is whether this markdown file is to be a text format or just source for a rendering. And given a population of people on both sides of that, which we obviously have, the next opinion-driven decision is whether to accommodate both or not.

As a text format, the question of "long enough to switch to lazy numbering is moot. A list of 1. is not a numbered list. It just has a clunky bullet.

This list can just be made better instead:

• it has a reference "go back to step 3" that would not refer to anything if there is no "3". TBH that could just be clearer with words, so I switched it.
• it has an extraneous nested list which is also numbered, super gross and even rendered that way by our website (GitHub does better)
• the outer and inner nested lists are both incorrect!

[kennknowles]

Random aside:

The guideline for when to use a numbered list vs bullets in writing is whether or not the order of the items matters. But in the case of programmers applying their "source/render/diff" brain to markdown they've invented a third category which might be useful if it really came into being as a thing in writing: a kind of bullet that indicates that the order matters, but that order is to be the textual order which was there all along. I'll say that I think ↳ is probably a nice symbol that communicates that intent more elegantly.

So, yea, I have maybe thought too much about this, because I care about writing and reading and language. I think the actual thing that has been created it way more interesting than its creators intended :-)

[damccorm]

I'm going to call out that I did the bad thing of saying "This isn't important enough to argue about", and then presented multiple arguments for why we should do it my way, but I do genuinely think this is not worth the discussion when really we just seem to have different values here (and probably the next person to edit the file will just change it anyways since neither of us is really talking about something systemic here).

With that said, I am going to bow out of this conversation instead of continuing because I don't want to stand in the way of you making things better with your PR.

[damccorm]

Other than mentioned changes, LGTM if we have consensus

[kennknowles]

Squashing fixup commits then checking it is still green before merge.