Re: [Proposal] Release Guide improvements

[Ahmet Altay <al...@google.com>]

Thanks a lot for doing this! :) It is a good improvement.

On Tue, Jan 26, 2021 at 4:12 PM Robert Burke <re...@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 <lo...@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
>>
>