Thanks a lot for doing this! :) It is a good improvement. On Tue, Jan 26, 2021 at 4:12 PM Robert Burke <r...@google.com> wrote:
> Dang it. Good catch. Thanks. > https://issues.apache.org/jira/browse/BEAM-11693 is the right JIRA. > > On Tue, Jan 26, 2021 at 3:56 PM Robert Burke <lostl...@apache.org> wrote: > >> Hello Beamers! >> >> I just filled a JIRA BEAM-11217 [1] to make some changes and update the >> content of the release guide, based on my experiences with running the >> 2.26.0 release. >> >> Overall, the content is pretty thorough, but it's been added to >> organically over time, and is due for a bit of a cleanup. My big issues >> were around consistency within the document itself, that not all pre-reqs >> for building artifacts are declared, and that it's very easy to lose track >> of what needs to be done. None are too hard to resolve, just need a few >> passes to clean them up. Who better than someone who recently ran through >> it (me)? >> >> I've got a PR 13815 [2] out now to address initial formatting issues >> which for the most part does not affect the content. The main visible >> change is the email template is fixed (it's not presently displayed), among >> a few minor content additions. >> >> After that, I'd like to rewrite the introduction to clarify the release >> process and goals (generate and publish artifacts), and clean up some of >> the constants and such we will use. Overall the goal is to make it easier >> for any committer to read the document and possibly run a release. There >> are certainly other changes we can do (like make a release environment >> container) >> >> I understand our wonderful tech writing folks are pretty busy right now >> with the other website changes. I certainly welcome their input, but likely >> don't need per-PR review for most of these changes. >> >> -------- >> >> One bigger change to the content that certainly warrants discussion here: >> I'd like to remove the manual command level copies of the automation >> scripts in the release document. >> >> My reasoning: They are redundant, leading to lengthy descriptions that >> are skipped if running the scripts in question. They're often not kept in >> sync with the scripts themselves. I propose we remove the copies from the >> guide *and* improve the documentation in the scripts themselves for those >> who wish to execute the command manually. This will better document what >> the scripts are doing, and avoids the redundancy, and the errors they can >> lead to. >> >> -------- >> >> If you'd like to be included on individual reviews, please let me know, >> and I'll add you to the various PRs. Otherwise, I'll be leaning on Pablo >> (2.27.0 release manager) and Cham (2.28.0 release manager) for reviews. >> >> Thank you for your time! >> Robert Burke (2.26.0 Release manager) >> >> >> [1] https://issues.apache.org/jira/browse/BEAM-11217 >> [2] https://github.com/apache/beam/pull/13815 >> >