Document contribution and editorial processes

[quaid]

First come first serve except:

• SMEs?
• not enough experience?
• more than one taker at a time?
• can't collaborate effectively to co-author?

[bproffitt]

https://github.com/theopensourceway/guidebook/blob/master/PROCESS.adoc

[bproffitt]

@semioticrobotic Can you review what I have so far? I think you will see the problem I ran into, which is how can we access review tools without doing a pull request?

So do a PR, you might say. Except you have to make a change before you can start a PR, and you have to assign someone else to review when you do a PR.

I'm stymied.

[semioticrobotic]

Happy to, @bproffitt.

You'll see my solution is not ideal: push editorial changes to the main branch, eschewing separate pull requests for each editorial pass. All editorial work is recorded in a diff and anyone can see changes there.

[bproffitt]

Okay. But what do editors do if they have a query? Without a pull request, we can't get to the Review tools, so no "annotation".

Thanks for finishing it. I think this is something for the Thursday meeting.

[semioticrobotic]

Great question, as I just encountered it in another project as you were typing this very comment! Editing some great new work from @funnelfiasco, I left an inline query in line 65.

Again, not ideal, I realize, but functional.

[semioticrobotic]

I agree that the annotation tools are beneficial, however, so if we'd like to use them we'd need to rethink the editorial workflow so that all editorial work occurs in individual branches, rather than in main, prior to a chapter merge.

[bproffitt]

Okay, that may work. Because the annotation tools of a review will only be available on the "wrong" side of an editor/contributor transaction. Even if we start doing PRs.

[semioticrobotic]

I see your point.

Note, too, that leaving comments inline is possible (for editors and reviewers with adequate permissions, natch) when viewing diffs. Just click the particular commit ID of the commit that interests you, then hover over a line to receive the "blue plus" icon. Click, add.

[funnelfiasco]

You wouldn't necessarily need a PR per-editorial interaction. You can leave the branch open as you go back and forth, rebasing the PR (by pushing to the branch) until it's ready to go live.

[semioticrobotic]

You wouldn't necessarily need a PR per-editorial interaction. You can leave the branch open as you go back and forth, rebasing the PR (by pushing to the branch) until it's ready to go live.

Thanks, @funnelfiasco! We discussed this briefly at a project sync but were worried that working branch-by-branch might add a prohibitive level of complexity for newcomers and folks not immediately familiar with Git/Hub. So we thought that perhaps just asking non-technically-minded editors, for example, to just hack on main would be easiest. But in the long run, it may not be!