GenomicsStandardsConsortium · cmungall · Nov 21, 2023 · Nov 21, 2023 · Nov 21, 2023 · Dec 4, 2023
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,65 +2,59 @@
 
 :+1: First of all: Thank you for taking the time to contribute!
 
-The following is a set of guidelines for contributing to
-mixs. These guidelines are not strict rules.
-Use your best judgment, and feel free to propose changes to this document
-in a pull request.
+The following is a set of general guidelines for contributing to MIxS. 
+
+For a more detailed guide to MIxS editing and contributing policies, see the [contributing documentation](https://github.com/GenomicsStandardsConsortium/mixs/blob/main/src/docs).
 
 ## Table Of Contents
 
+* [Introduction](#introduction)
 * [Code of Conduct](#code-of-conduct)
+* [MIxS transition to LinkML ](linkml)
 * [Guidelines for Contributions and Requests](#contributions)
-  * [Reporting problems with the data model](#reporting-bugs)
-  * [Requesting new terms](#requesting-terms)
-  * [Adding new terms yourself](#adding-terms)
 * [Best Practices](#best-practices)
   * [How to write a great issue](#great-issues)
   * [How to create a great pull/merge request](#great-pulls)
 
-<a id="code-of-conduct"></a>
-
-## Code of Conduct
-
-The mixs team strives to create a
-welcoming environment for editors, users and other contributors.
-Please carefully read our [Code of Conduct](CODE_OF_CONDUCT.md).
+<a id="introduction"></a>
+## Introduction
 
-<a id="contributions"></a>
+The Minimum Information about any(x) Sequence (MIxS) standard, maintained by the Genomic Standards Consortium (GSC), is community built and developed to improve FAIR (findable, accessible, interoperable, and reusable) data and data sharing. Below you'll find documentation on how to contribute to or make suggested changes to the GSC's MIxS standard. Additionally, you'll find policies about workflows and requirements for contributions.
 
-## Guidelines for Contributions and Requests
+MIxS static documentation lives in this repo under src/docs as markdown files. Where applicable, static documents will be used to create GSC website pages.
 
-<a id="reporting-bugs"></a>
+<a id="code-of-conduct"></a>
+## Code of Conduct
 
-### Reporting problems with the data model
+The mixs team strives to create a welcoming environment for editors, users and other contributors.
+Please carefully read our [Code of Conduct](CODE_OF_CONDUCT.md).
 
-Please use our [Issue Tracker][issues] to report problems with the ontology.
+<a id="linkml"></a>
+## MIxS transition to LinkML 
 
-<a id="requesting-terms"></a>
+With the release of MIxS 6.0, management of MIxS switched to fully using GitHub for edits and releases and to using [Linkml](https://linkml.io/) to define the MIxS schema. The release of MIxS 6.2.0 made the switch to using "out of the box" LinkML code rather than customizations. The biggest change was to remove any dependencies on an external spreadsheet for generating LinkML YAML files. The source of truth (SOT) for editing MIxS is now [the YAML file](https://github.com/GenomicsStandardsConsortium/mixs/blob/main/src/mixs/schema/mixs.yaml). However, since this was a minor release, most repositories implementing MIxS will continue to use the generated artifacts from MIxS 6.1 until MIxS 7 is released.
 
-### Requesting new terms
+This section will be update or deleted after the release of MIxS 7.
 
-Please use our [Issue Tracker][issues] to request a new term for the ontology.
+<a id="contributions"></a>
+## Guidelines for Contributions and Requests
 
-<a id="adding-terms"></a>
+Please review the [MIxS editing policies](policy.md) before making contributions to this repo.
 
-### Adding new terms yourself
+For guidance on how to request a new checklist or package, request a new term or update to an existing term, or report an issue with the MIxS code, please see [the workflows document](worklow.md).
 
-Please submit a [Pull Request][pulls] to submit a new term for consideration.
+For guidance on how to use LinkML or contribute to the core LinkML code, please see [the LinkML documentation](https://linkml.io/linkml/).
 
 <a id="best-practices"></a>
-
 ## Best Practices
 
 <a id="great-issues"></a>
-
 ### How to write a great issue
 
 Please review GitHub's overview article,
 ["Tracking Your Work with Issues"][about-issues].
 
 <a id="great-pulls"></a>
-
 ### How to create a great pull/merge request
 
 Please review GitHub's article, ["About Pull Requests"][about-pulls],

diff --git a/src/docs/README.md b/src/docs/README.md
@@ -0,0 +1,40 @@
+# MIxS Repository Documentation
+This folder contains static documents that describe this repository, its editing policies, and workflows and guidance for editing.
+
+For information on GSC see [The GSC website](https://www.gensc.org/)
+
+For information on MIxS and its use, see [its autogenerated documentation](https://w3id.org/mixs).
+
+The GSC uses LinkML tooling to maintain the MIxS schema. For guidance on how to use LinkML or contribute to the core LinkML code, please see [the LinkML documentation](https://linkml.io/linkml/).
+
+## Code of Conduct
+
+The MIxS team strives to create a welcoming environment for editors, users and other contributors.
+Please carefully read our [Code of Conduct](../../CODE_OF_CONDUCT.md) before making a contribution.
+
+## Folder contents
+
+* README.md: This file
+* [about.md](about.md): A description of MIxS. This file is auto-generated by LinkML. For more information on MIxS, see [its autogenerated documentation](https://w3id.org/mixs).
+* [edit_worklow.md](edit_worklow.md): Guidance for members of the GSC Technical Working Group on how to request and create a new checklist or package, request and create a new term, update an existing term, or report an issue with the MIxS code
+* [external_contribution.md](external_contribution.md): Guidance and how-to's for external contributors, including how to request changes or report bugs
+* [policy.md](policy.md): Policies for editing, versioning, and communication about MIxS releases
+
+## GitHub Best Practices
+### How to write a great issue
+
+Please review GitHub's overview article,
+["Tracking Your Work with Issues"][about-issues].
+
+**Labeling issues:** Issue labeld were updated 2023/12. Please do not create new labels on your own. Instead, create an issue to request a new label, which will be reviewed by the TWG or CIG. See the [labels page](https://github.com/GenomicsStandardsConsortium/mixs/labels) for descriptions of existing issues.
+
+### How to create a great pull/merge request
+
+Please review GitHub's article, ["About Pull Requests"][about-pulls],
+and make your changes on a [new branch][about-branches].
+
+[about-branches]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches
+[about-issues]: https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues
+[about-pulls]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
+[issues]: https://github.com/GenomicsStandardsConsortium/mixs/issues/
+[pulls]: https://github.com/GenomicsStandardsConsortium/mixs/pulls/
diff --git a/src/docs/about.md b/src/docs/about.md
@@ -1,3 +1,5 @@
 # mixs
 
-MIxS: the Minimum Information about any (X) Sequence standard
+MIxS: the Minimum Information about any (X) Sequence standard.
+
+This file is auto-generated by LinkML. For more information on MIxS, see [its autogenerated documentation](https://w3id.org/mixs).
diff --git a/src/docs/edit_workflow.md b/src/docs/edit_workflow.md
@@ -0,0 +1,75 @@
+# MIxS Editing Workflows and Good Practices
+
+Please try to follow this document. First read the [policies](policies) document.
+
+# Terms
+
+## Requesting and creating a new term
+
+## Requesting and implementing a term update
+
+
+## Requesting and implementing a term deprecation 
+
+# Checklists, extensions, and combinations
+
+Define what they are
+
+## Requesting and creating a new checklist or extension
+
+## Updating an existing checklist or extension
+
+# Releases
+
+# LinkML Updates 
+
+# Documentation
+Autogenerated documentation is created with every PR
+Sujay's fork allows you to preview what will be regenerated. Important for when the documentation technology changes.
+
+------------------
+Content copied over:
+
+- All change requests to the GSC should be captured in an issue.
+   - Issues should be descriptive and provide clear requests and changes. Issue templates are available and should be used when possible.
+   - One change should be proposed per issue. If multiple issues are related, you can leverage a GitHub super issue to connect related items.
+
+- All branches should be tied to issues and the branch name should relate to the issue it's tied to.
+  - This can be accomplished easily using the GitHub "create a branch" tool when viewing the issue on the webpage.
+
+- All pushes, pull requests, and changes should be related to a single issue, and issues should be a single change per issue.
+  - Issues and their associated pull requests should be small and targeted. One change per issue and pull request.
+
+- All branches and pull requests should be tied to an issue.
+
+- When making a pull request, contributions can continue to be made and built, but within scope of the related issue.
+  - Making a draft pull request can be done to confirm changes are being done correctly
+
+- Provide a reviewer for pull requests. 
+  - Pull requests must be reviewed by a member of the GSC Technical Working Group
+  - A Pull request requires someone other than the person that created the pull request
+  - Include issue author as a pull request reviewer
+
+- Once a pull request is started, all further discussion, review, and changes, happen in the pull request (rather than the issue). 
+  - ?? Using conversations within PRs (TODO: add links to GH documentation)
+
+- When a pull request is merged, the associated branch should be deleted and issue closed.
+
+- The GSC will create releases (ADD Details, # of PRs? on a schedule?)
+  - The GSC will use semantic versioning for releases: 3 digits (major, minor, patch)
+  - Create a project for the release or other large change set
+  - A change log for a release will be generated from all the pull requests that are part of the repository since the last release.
+
+- All issues that pertain to a release should be part of a project for that release.
+
+- Contributions should NOT be made in a fork. 
+  - If external parties make a fork, it should be tied to an issue. Forks will only be merged back in following the above criteria for branches and small changes.
+  - It is expected that external parties will discuss with the Technical Working Group before making changes on a scale that require a fork (e.g. a new checklist or extension).
+  - The preference is to avoid forks and will be reviewed on a case by case basis.
+  - Whenever a fork is created, a Technical Working Group member will reach out to the creator
+
+- Add require a description to the suggested new thing to the requirements
+- New extensions or checklists should be tracked using GitHub Projects
+
+- Add require a description to the suggested new thing to the requirements
+- New extensions or checklists should be tracked using GitHub Projects
diff --git a/src/docs/external_contribution.md b/src/docs/external_contribution.md
@@ -0,0 +1 @@
+# Guidance and How-To's for External Contributors
diff --git a/src/docs/policy.md b/src/docs/policy.md
@@ -0,0 +1,79 @@
+# Introduction
+
+This document records policies about editing and contributing to MIxS which are enacted via [editing workflows](workflow.md). Documentation in this repository is considered authoritative and supercedes any previous documentation in Google Drive or the gensc.org website, although content from this repository may be duplicated in those or other locations. All new editing and contributing policies must be approved by the Technical Working Group (TWG) and Compliance and Interoperability Group (CIG).
+
+## MIxS transition to LinkML Details
+
+With the release of MIxS 6.0, management of MIxS switched to fulling using GitHub for edits and releases and to using [Linkml](https://linkml.io/). The release of MIxS 6.2.0 made the switch to using "out of the box" LinkML code rather than customizations. The biggest changes was to remove any dependencies on an external spreadsheet for generating the LinkML YAML file. The source of truth (SOT) for editing MIxS is now [the YAML file](https://github.com/GenomicsStandardsConsortium/mixs/blob/main/src/mixs/schema/mixs.yaml). However, since this was a minor release, most repositories implementing MIxS will continue to use the generated artifacts from MIxS 6.1 until MIxS 7 is released.
+
+NOTE: Update this section after the release of MIxS 7.
+
+# GitHub Editing Policies
+
+The GSC leverages GitHub tools to manage MIxS terms, checklists, extensions, and releases. GSC meeting notes, including CIG, TWG, and Board meetings, are NOT authoritative but exist to support development in this repository. GitHub issues, pull requests, and releases will contain the source of truth. Documentation will be generated from GitHub. Below are guidance and policies on how to contribute to MIxS. Specific details on how to use GitHub for contributions are available in the [editing workflows](workflow.md) document.
+
+### Editing policies
+* All change requests to the GSC should be captured in an issue.
+  * Issues should be descriptive and provide clear requests and changes. Issue templates are available and should be used when possible.
+  *  One change should be proposed per issue. If multiple issues are related, you can leverage a GitHub super issue to connect related items.
+* All branches should be tied to issues and the branch name should relate to the issue it's tied to.
+  * More details on how to easily accomplish this using the GitHub "create a branch" tool are provided in the editing workflows.
+* All pushes, pull requests, and changes should be related to a single issue, and issues should be a single change per issue.
+  * Issues and their associated pull requests should be small and targeted. One change per issue and pull request.
+* All pull requests (PRs) must be reviewed by at least one other person besides the requester who is a member of the TWG. Additional reviewers are encouraged.
+  * If the issue author does not make the PR, they should be included as a pull request reviewer.
+
+**TODO:** Add policy about who can commit directly to mixs repo and merge pull requests. CREATE AN ISSUE FOR THIS!!!
+* should anyone be allowed to commit directly to main (PRs are merged, not committed)
+* rules  allow us to control this
+* Who has permission to create branches is controlled by roles
+
+# Release Policies
+The GSC (through the CIG and with support from the TWG) creates major releases for MIxS approximately one time per year. MIxS uses semantic versioning for releases: 3 digits (major, minor, patch).
+
+## Major Releases
+* Before a major release, the CIG and TWG must generate a release candidate.
+* Major releases contain new checklists, extensions, and terms.
+* Major releases may also include the types of changes allowed in minor or patch releases.
+* Major releases must be reviewed by the CIG, TWG, GSC board, and the list of repositories using MIxS.
+  * TODO: Create a list in this repo of who are external reviews. Assign a responsible person to maintain that list and to maintain the emails in a separate private document.
+* The CIG manages the distribution of and feedback from major releases and provides outreach about new releases.
+* At least x months must be provided for feedback on major releases before they are published.
+* Repositories that are MIxS compliant must adopt major releases within X months of their release.
+
+## Minor Releases
+* Before a minor release, the CIG and TWG must generate a release candidate.
+* Minor releases CANNOT contain new checklists or extensions.
+* Minor releases can include updates to existing terms.
+* Minor releases may include new terms, but those terms are not consider "official" until the next major release. **TODO:**  Discuss this policy
+* Minor releases must be reviewed by the CIG and TWG. Other interested parties may review minor releases using GitHub.
+* Depending on whether the minor release is more technical or content focused, either the TWG or CIG manages the distribution of and feedback and provides outreach about new minor releases.
+* At least x weeks must be provided for feedback on major releases before they are published.
+* Repositories that are MIxS compliant are not required to adopt minor releases.
+
+## Patch Releases
+* Patch releases are used to correct errors in elements (checklists, extensions, or terms) that do no substantively change the content of the element.
+* Patch releases may be used to update documentation.
+
+# Policies for Community Contributions to MIxS
+
+This section provides policies about contributing to MIxS. See the [editing workflows](workflow.md) document for how to request, update, or deprecate a checklist, extension, or term.
+
+It is the responsibility of the CIG to work with contributors to ensure that their proposal meets MIxS and GSC requirements for content. It is the responsibility of the TWG to work with the CIG and external contributors to ensure that proposed changes meet MIxS technical requirments. 
+
+## Checklists and Extension
+
+Most new checklists, extensions, and combinations are contributed to MIxS by external research communities. If an indivudual or single organization wants a new checklist or extension, we strongly recommend that they first enlist broad participation from the relevant community to ensure that the request is supported by community consensus. Often, the community has spent considerable time defining their contribution before approaching MIxS, but we encourage communities to engage with the GSC as early as possible. 
+
+See the MIxS documentation for a definitions of checklist, extension, and combination. **TODO:** Add link when it is ready.
+
+## Terms
+
+Changes to terms (addtion, deletion/deprecation, modification) are made by individuals, organizations (e.g., repositories working with MIxS), or communities. They may stand along or part of a new checklist or extension.
+
+Procedures for changing terms are described in the [editing workflows](workflow.md) document. All terms related requests must come through an issue in this GitHub repository. 
+
+# What it means to be MIxS Compliant
+As a standards organization, GSC has expections of what it means to be compliant with their standards. For MIxS, this  means...
+
+**TODO:** Decide on and document what MIxS Compliant means and if/how to enforce it.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		# Guidance and How-To's for External Contributors