MIxS Editing workflow and policy

[ramonawalls]

A first draft of the specific steps for making changes to MIxS after release 6.2 is in the following comment.

This workflow It will be a markdown page in the MIxS repo that will link from the main MIxS readme and GSC website. It should be somewhere in the MIxS autogenerated documentation as well.

The workflow will need to be approved by the CIG.

NOTE: Move this issue into the main MIxS repo - DONE

[ramonawalls]

Steps to be discussed by the TWG:

• Use semantic versioning: 3 digits (major, minor, patch)
• Create a project for the release or other large change set
• Creating and issues
• • Each proposed change to MIxS must be documented in an issue.
• • Generally, keep it to one change per issue, e.g., one new term, one new lml class. If an issue is such that it must have multiple changes, be sure every commit mentions that issue.
• Create a branch for the issue - This can be done from within the issue, it will be title by the issue
• • Make any changes that address the issue happen in that branch
• Make a PR for that branch when the work has been mostly complete
• • Request review of the PR
• • PRs must be reviewed by a member of the TWG who did not create the PR.
• • Once the PR is started, all further discussion happens there (rather than the issue). Using conversations within PRs (TODO: add links to GH documentation)
• When a PR is merged, the corresponding issues will be closed, if it is linked to the issue
• All issues that pertain to a release should be part of a project for that release.
• Create a release
• • Change log for a release will be generated from all of the PRs that are part of the repo since the last release. You can click on since which release you want to include the PRs

Note:

• Meeting notes are not authoritative. Only GH issues, PRs and releases, plus sometimes LinkML and website documentation, but those should also be based on issues.

[only1chunts]

Thanks Ramona. I have some questions (that are possibly more to do with lack of knowledge about GitHub!)
Under the scenario of a new extension being created by a collaborator:
Where should the extension Project be created? i.e. is in the Main branch or in an extension-specific fork?
Do Forks synchronise their issue tickets with the main branch somehow? If not, where should tickets be discussed, in a extension project branch or in the Main branch? If the main branch does the referencing of tickets in the main branch work within a extension-specific fork?
If possible we should organise a call to set up an MINAS extension test run to see how it works in practice, they already have a project in Main.

[ramonawalls]

These are great questions, @only1chunts.

If a CIG editor is making a new checklist or extension (which I think is more often), it could be done on a branch of the main repo, because we can manage the project, issues, and PRs in the same repository.

I think if an external collaborator is making a PR for a new extension or checklist, it should be done on a fork. However, I am pretty sure that issues from forks do not merge back into the main repository. If we put the project and issues in the main repo, they can still be referenced from a commit message or PR in a fork in our gsc org or another org, but I don't if know if they can be closed from that fork.

Perhaps @turbomam or @sujaypatil96 can advise us at the next TWG on Tuesday.

Answer: Issues in a fork do not merge back to origin when the fork is merged. Therefor, all forks should be based on an issue in the mixs repo.

[ramonawalls]

Editing in a FORK

• External parties can create a fork to suggest changes
• Link to GH documentation on forking and PR processes
• Fork should create an issue in the MIxS main repo and refer to it in their PR

[ramonawalls]

Policy:

• Our assumption is that external parties will talk to us before making changes on a scale that require a fork (e.g. a new checklist). In that case, we can work with them to create a branch and avoid forking.
• Forks would be an irregular use case, and it should probably be reviewed on a case by case basis.
• Whenever we see a fork being make, a TWG editor should reach out to the person.

[ramonawalls]

Static documentation should live under src/docs as MD files.

[mslarae13]

Relates to #607

I've started a file, Ramona if you can let me know the additional details you want I'll get them in the the file I started and push it up

[ramonawalls]

@mslarae13 Where can I see the content you have been working on and how can I contribute?

[mslarae13]

See https://github.com/GenomicsStandardsConsortium/mixs/blob/606-mixs-editing-workflow-and-policy/src/docs/contribution-policy.md

@ramonawalls feel free to check out my branch, make some edits and put in the PR :)