Define a set of rules and process for merging

[andorsk]

Define a set of rules and process for merging. This involves figuring out who is capable of merging back to master.

[andorsk]

@wenjing suggested break out: Editor and Maintainer.

Antti:

• Maintainer decides what goes into which version. Own the document/published version.
• Someone needs to decide who goes into the release.

Abbie:

• Lead editor.

Drummond:

• No formal role of lead editor but someone would step up.

[a-fox]

I think this issue is inherently wider than just merging. We should describe the contribution & editing process, including Branching, Pull Request & Merging process. This is also closely tied in with the Labels & issue management process, as we tag the issue with PR's & merge-ready labels.

I've previously used Gitflow (https://www.gitkraken.com/learn/git/git-flow), but it's too complex for mere document management. However, GitHub Flow seems to be much simpler and would work fine for our needs.

For the process & rules, I propose the following:

Branching & Tagging:

• The main-branch should always have the latest approved changes
• custom "feature" branches may be used for special purposes, e.g. for groups to work on a larger section of text
• Version tags are used for each release of the document
• Releases should be versioned and if needed, appended with a pre-release tag, e.g. "v1", "v3-RC1", "v4-IIW39"
• Versioning should be simple, only major releases numbered, prepended with letter v. e.g. v1, v2, v3.

Changes to document

• Change proposals can be made by anyone by creating an issue in Git and proposing a pull request against the main branch, containing the proposed changes.
• Change proposals are made as according to the process below
• Editors may make changes to the main branch without creating an issue, in the case where an issue has not been already created. If an issue already exists for the change, the editor should follow the standard review process and refer the PR in the issue

Editing Git process 1) Create a clone of the repo 2) Make changes to the document on your own repo 3) Ensure commit history sync by rebasing own repo with 'git pull rebase' 4) Create a pull request against the ToIP repo main branch 5) Refer to the PR in the relevant issue(s). 6) Contributor sets the issue to label "Needs review" to signal editors to review the changes

Review & Merge Process

• Review of PR's is done by appointed editors
• Issues labeled with "Needs review" should contain a PR code OR the change text directly in the issue (for those not Git-savvy)
• If the PR is ready to be merged, it is tagged with "Accepted" -label
• In normal circumstances, any editor may merge changes tagged with label 'Accepted'
• The editor can try to merge the PR to the main branch.
• If PR is not rebased and commit histories are not in sync, the PR can be merged if there are no overlapping changes with the history. In this case it is the merging editor's responsibility to ensure that the merging is clean and no unwanted changes happen.
• In case of change conflicts, the editor requests the PR creator to rebase against current main branch and resubmit the PR.
• Sometimes the editor group may agree to a controlled merging process and decide that merging happens only by a selected editor (e.g. release owner) or during editor meetings. This may happen when a release of the document is coming soon and only some specific changes are allowed.

[andorsk]

I'll take putting this into a formal PR for the next call! Thanks @a-fox for the awesome comments here. Will probably take this w/ some modifications.

[talltree]

@a-fox Thank you for taking the time for such a detailed proposal. I'm not a GitHub expert, so this all seems to make sense to me. I will leave it up to the set of Editors who volunteer to be Maintainers (of which I hope you will be one, and @andorsk has also volunteered) to work this out to your satisfaction.

[a-fox]

I think the key point of decision is to agree the merging/maintaining process: 1) Initially all editors are allowed to merge new changes 2) Editor group may choose a time of controlled merging, when only selected people mantain merging 3) Maintainers are there to manage the merging, maintaining and publishing process technically.

Does this sound ok?

[talltree]

I'll take putting this into a formal PR for the next call! Thanks @a-fox for the awesome comments here. Will probably take this w/ some modifications.

@andorsk Since this issue isn't about the spec, but rather about our repo maintenance process, rather than a PR, I would propose that we document this in another wiki page just like the Github Issue Management page we just created today.

To make it easy, I just created that new wiki page: Github Repo Management.

Since @a-fox has proposed a process, I'm assigning him alongside you on this issue so the two of you can work out your proposed process on that wiki page. As soon as you have a draft you both like, add a comment back here and change the label to status: needs-review.

[andorsk]

@talltree I'm fine with maintaining a separate clone of the documents, (and I'm happy to copy things over after things are settled) but I think Github needs to be the single source of truth when it comes to the process and in terms of design process a PR actually does provide a good way to iterate, design, and handle it (at least IMO ).

Typically, a file like the GOVERNANCE.md and CONTRIBUTING.md file will provide the guidelines for governance of the repo. That file would be submitted and iterated over a PR. Samples are on the links.

I'll say this: From my personal experience, I actually find it more productive to run a PR with a proposal, then iterate on it with collaborators. I'm happy to do it over Confluence, as I'm not trying to make it difficult on purpose, but want to put it out there this might be a good opportunity to work through a different flow that's a little more lined up with the "git" process.

I understand that everyone is at different levels of familiarity with Git, so maybe I'm thinking a little bit too much like I would in a more Git friendly context, so please push back on this if you think it's appropriate.

Let me know where you guys are on this, and I'll go with it. I want to clarify I'm not opposed to using the page @talltree provided, but wanted to float this by first and see what you think.

[andorsk]

https://github.com/trustoverip/TechArch/pull/49 has some work around this and is in DRAFT.

[andorsk]

Current version: https://github.com/trustoverip/TechArch/blob/339dc1cf4bd0c7d226520dc963a1b9726937a020/CONTRIBUTING.md to be reviewed.