This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Last revision Both sides next revision | ||
github_exp_2021_feedback [2021/02/24 21:58] sginoza |
github_exp_2021_feedback [2021/05/18 14:32] sginoza |
||
---|---|---|---|
Line 2: | Line 2: | ||
Please see [[github_auth48_experiment]] for context. | Please see [[github_auth48_experiment]] for context. | ||
+ | |||
+ | ==== Feedback from Justin Uberti (author, RFC 8829) ==== | ||
+ | |||
+ | < | ||
+ | Summary: | ||
+ | This was the first time I've had such a long document go through the | ||
+ | AUTH48 process, but from my perspective things worked much better than | ||
+ | they would have using email. | ||
+ | |||
+ | There were literally almost 100 separate changes to the text during AUTH48 | ||
+ | (not sure if this is typical or not for this size of document). Being able | ||
+ | to track each of these individually, | ||
+ | issue, distribute the work across the authoring team and Jean, bring people | ||
+ | in to comment on specific issues, and finally review proposed changes with | ||
+ | full diffs and ability to easily discuss the diffs - each of these was a | ||
+ | significant efficiency improvement from my perspective. However, of all | ||
+ | of these, the separate tracking for each issue (rather than a single | ||
+ | ginormous email) was the biggest improvement IMO. | ||
+ | |||
+ | In the end I felt that we were able to resolve all ~100 issues that were | ||
+ | raised as part of AUTH48 completely and improve the document' | ||
+ | and readability as a result. | ||
+ | |||
+ | Here's what specifically worked well: | ||
+ | 1) I wrote some scripting to parse the initial auth48 mail and turn that | ||
+ | into ~60 separate github issues. This let each issue easily be discussed | ||
+ | independently. | ||
+ | 2) I triaged the issues, and those that seemed pretty straightforward | ||
+ | I marked as ' | ||
+ | comments to the specific issue. | ||
+ | 3) Those that weren' | ||
+ | authoring team to track down the right solution, at which point they | ||
+ | were then assigned as in 2). | ||
+ | 4) When new questions came up, the editors or Jean would file new Github issues. | ||
+ | 5) To address the issues assigned to her, Jean would create pull | ||
+ | requests with her proposed changes, tagging the issues that the pull | ||
+ | request was addressing. | ||
+ | 6) I would review the pull request and either send comments back to | ||
+ | Jean for further changes (through the pull request review tool) or | ||
+ | merge the PR into the document. | ||
+ | 7) When the PR was merged, the relevant issues were then closed, | ||
+ | allowing us to easily track our progress via the size of the issues list. | ||
+ | 8) In cases where the authoring team couldn' | ||
+ | we pulled relevant people (e.g., Adam Roach) into discussions to figure | ||
+ | out a solution. | ||
+ | |||
+ | Here's what could have worked better: | ||
+ | a) as noted in 1) above, I had to write some Python to parse the email and call | ||
+ | the Github API to create the issues. It would be better to have a tool that would | ||
+ | let the RFC Editor directly create these issues, rather than trying to serialize | ||
+ | to/from email. | ||
+ | b) we worked on a parallel branch to the main document, meaning that the main | ||
+ | branch was frozen at jsep-24, and then a separate branch ' | ||
+ | RFC Editor' | ||
+ | comments. This approach, while it avoided changing the ' | ||
+ | anything that wasn't fully vetted, ended up causing confusion. Working directly | ||
+ | against master would have been easier. | ||
+ | c) the saga of #843 is a long and complicated story, but I think this issue is | ||
+ | largely separate from the GitHub experiment. Neither the JSEP nor BUNDLE editors | ||
+ | fully understood the conflict until it was too late, and a short meeting back | ||
+ | in 2018 would probably have avoided the issue. | ||
+ | |||
+ | You are welcome to add my feedback to the experiment page - happy to provide | ||
+ | more details as needed. | ||
+ | |||
+ | Justin | ||
+ | </ | ||
+ | |||
+ | |||
==== Feedback from RFC Editor (regarding RFC 8829) ==== | ==== Feedback from RFC Editor (regarding RFC 8829) ==== |