Address comments

docs/about.md

@@ -10,13 +10,6 @@ represent many open source projects in the scientific community, specifically
 
 This project is funded by a grant from the [Alfred P. Sloan Foundation](https://sloan.org/).
 
-## Code of Conduct
-
-The Executable Book Project follows a community
-[Code of Conduct](https://github.com/executablebooks/.github/blob/master/CODE_OF_CONDUCT.md).
-Please use that document as the source of truth for interacting with the EBP
-community.
-
 ## Our technical goals
 
 The goal of the EBP is to build tools that facilitate creating

docs/bootstrap-governance/code-of-conduct.md

@@ -0,0 +1,13 @@
+(policy:coc)=
+# Code of Conduct
+
+:::{note}
+
+This is an informal Code of Conduct, and is used as a stand-in best practice until we formally define a CoC and response process for this community.
+
+:::
+
+The Executable Book Project follows a community
+[Code of Conduct](https://github.com/executablebooks/.github/blob/master/CODE_OF_CONDUCT.md).
+Please use that document as the source of truth for interacting with the EBP
+community.

docs/bootstrap-governance/governance.md

@@ -0,0 +1,137 @@
+# Governance of Executable Books
+
+```{note}
+_All contributors_ to the Executable Books Project (including but not limited to individuals contributing code, providing technical support, teaching workshops, and engaging in discussions about changes to EBP policy or the MyST Specification) adhere to the [Code of Conduct](policy:coc).
+```
+
+This page describes the groups of people with decision-making authority in the project, as well as the Sources of Truth for organizational policy and the process around changing it.
+
+## Decision-making groups
+
+### Steering Council
+
+Have decision-making authority over the entire organization.
+Their primary duty is to set organizational policy and strategy, to steward all technical and IP assets of the organization, to make decisions when we are at an impasse, and to delegate decision-making power to others in the organization. 
+
+The Steering Council is currently comprised of the three Principal Investigators of the original grant funding the project: [Chris Holdgraf](https://github.com/choldgraf), [John Stachurski](https://github.com/jstac), and [Greg Caporaso](https://github.com/gregcaporaso).
+
+```{note}
+We expect the Steering Council to expand in the future, and this initial Steering Council will define policies that set the expectations for steering council membership as well as the process for modifying or expanding the steering council membership in the future.
+```
+
+#### Responsibilies
+
+```{note}
+This is intentionally blank for now, we will add more information in the coming weeks.
+```
+
+% - Define organizational policy, strategy, and values
+% - Hold the community accountable to its mission and its code of conduct
+% - Oversee the structure and system of work in the community
+% - Delegate authority and responsibility to position the project for success
+
+#### Expectations
+
+```{note}
+This is intentionally simple for now, we will add more information in the coming weeks.
+```
+
+Steering Council Members agree to abide by the [EBP Code of Conduct](policy:coc).
+
+
+#### Privileges
+
+- _Owner_ status of the [executablebooks](https://github.com/executablebooks) GitHub organizations and repositories.
+- Access to any credentials or accounts that the project uses. At least two Steering Council members must have access to all project credentials.
+- All [Core Team privileges](governance:privileges:core-team)=
+
+### Core team members
+
+Individuals who are particularly interested in the EBP community and have demonstrated a willingness to participate in our community and further its mission. They guide discussion, grow the community, contribute code, and generally help the project improve.
+
+Currently the core team is [defined here](https://executablebooks.org/en/latest/team.html).
+
+#### Responsibilities
+
+```{note}
+This is intentionally blank for now, we will add more information in the coming weeks.
+```
+
+
+#### Expectations
+
+```{note}
+This is intentionally simple for now, we will add more information in the coming weeks.
+```
+
+Core Team Members agree to abide by the [EBP Code of Conduct](https://github.com/executablebooks/.github/blob/master/CODE_OF_CONDUCT.md).
+
+(governance:privileges:core-team)=
+#### Privileges
+
+```{note}
+This is intentionally simple for now, we will add more information in the coming weeks.
+```
+
+- Write permissions for any repository they are willing to steward.
+- Voting privileges for [MyST Enhancement Proposals](governance:meps).
+
+## Sources of truth
+
+### Team Policy
+
+Team Policy is defined at the [`executablebooks/team-compass`](https://github.com/executablebooks/team-compass) repository. 
+
+Our Team Compass is the Source of Truth (SoT) for all organizational policy[^1]. The Team Compass should make it clear what is _policy_ and what is _guidance_. It should define clear sections that are community "musts" and others that are "guidelines and recommendations".
+
+It can also delegate SoT status to other places in the organization. It delegates the SoT for the MyST specification to `myst-specification/`.
+
+[^1]: A Team Compass is common in the Jupyter ecoystem (e.g., [here is JupyterHub's Team Compass](https://jupyterhub-team-compass.readthedocs.io/en/latest/index-team_guides.html). In fact, Jupyter's governance model will soon [require that sub-projects have their own Team Compass](https://jupyter.org/governance/software_subprojects.html?responsibilities-of-jupyter-subprojects)
+
+(governance:policy-decision)=
+#### How to change team policy
+
+Take the following steps for changing any policy, strategy, or governance aspect of the Team Compass.
+
+1. **Open an issue** to explain the policy that you'd like to change, and why. Here is a rough template to follow:
+   ```
+   ## Context
+   
+   provide context needed to understand this proposal. Describe the problem this proposal will solve.
+   
+   ## Proposal
+   
+   describe your proposal in informal but specific terms.
+   
+   ## Impact
+   
+   describe the implications of this proposal and the impact it will have.
+   ```
+2. **Discuss and incorporate feedback** with others on the team. If there are objections or suggestions, do your best to incorporate them into your proposal.
+3. **Make a Pull Request** to the `Team Compass` repository (or another location if appropriate) and link it to the issue. This is the "formal change" that you wish to make.
+4. **Make a decision**. Steering Council members may approve PRs to change policy. To approve a change, use the "Approve" feature in the GitHub UI. To request blocking changes, use the "Request Changes" feature in the GitHub UI[^blocking]. PRs to change organizational policy may be merged when the following conditions are met:
+   - Have been open for five working days
+   - Have `Approval` from at least **One  Steering Council member**
+   - Have no `Request Changes` from a Steering Council member.
+   - If there are unresolveable objections from a Steering Council member, a decision to merge is made with a majority vote.
+   - If all steering council members `Approve`, it may be merged any time, overriding the requirement of being open for five working days.
+
+
+[^blocking]: When blocking any change or objecting to a proposal, provide a rationale for what must be changed and why you believe it is critically important. _Do not disapprove because of differences in opinion. Only disapprove if you have a major strategic concern_. See [Strategies for integrating objections](https://www.sociocracyforall.org/strategies-for-integrating-objections/) for what we are aiming for.
+
+
+### The MyST Specification
+
+The MyST Specification is defined at [`executablebooks/myst-specification`](https://github.com/executablebooks/myst-specification). The process for changing it is defined at [`executablebooks/myst-enhancement-proposals`](https://github.com/executablebooks/myst-enhancement-proposals).
+
+`executablebooks/myst-specification` is the Source of Truth for the MyST Specification. It uses a combination of documentation, examples, schemas, tests, etc to define MyST markdown in a form that others could use to implement parsers and renderers. It is versioned and includes "releases" in order to make it easy for downstream implementors to track the changes they need to make.
+
+```{admonition} Implementation detail
+This repository will need to be modified as-needed to be the source of truth for the MyST Specification, and to have enough information to teach newcomers about its structure and function. One example for inspiration: [the Zarr specifications page](https://zarr.readthedocs.io/en/stable/spec.html). [Here's a comment with some suggestions for what is missing](https://github.com/executablebooks/meta/pull/843#issuecomment-1275474229).
+```
+
+The MyST Specification is changed through the MyST Enhancement Proposal process, described below.
+
+#### How to change the MyST specification: MyST Enhancement Proposals
+
+See [](meps.md).

docs/bootstrap-governance/index.md

@@ -0,0 +1,30 @@
+# A bootstrap decision-making process and source of truth for Executable Books
+
+
+:::{note}
+
+This is a proposal for bootstrapping a formal decision-making and team policy process.
+It proposes a new location for organizational policy - a `team-compass`, but since this space does not currently exist, I am making this "proposal" by adding it as a PR to the `meta/` repository, which is currently our home for organizational policy. If accepted, I will remove this page and migrate content over to `compass.executablebooks.org`.
+
+:::
+
+These pages contain a bootstrap plan for encoding the Executable Books team policy and decision-making process. Its goal is to be as simple as possible and not deviate too much from our current practices (to maximize the chances of being followed). It also aims to balance "formal process" against "efficient asynchronous decision-making" (to avoid being so slow that it hinders the organization).
+
+It is split into a few pages to make it easier to read, review, and implement:
+
+```{toctree}
+code-of-conduct
+governance
+meps
+```
+
+Over time, as we learn what works and what doesn't, we may make amendments to this process to make it more complex.
+
+## Acknowledgements
+
+This builds off of the work that Chris Sewell did in creating the current [MyST Enhancement Proposals repository](https://myst-enhancement-proposals.readthedocs.io/en/latest/mep-0001.html). It takes much of the process there, and tries to simplify and slim it down. It also separates out two different processes - a more complex one for MyST, and a simpler one for organizational policy. We can revisit this in the future if we believe that we _need_ more complexity in one or the other. Many thanks to Chris S (and others) for feedback and inspiration for these ideas.
+
+
+## License
+
+All documentation in our Team Compass and MyST Enhancement Proposal repository are licensed under the [`CC0-1.0-Universal license`](https://creativecommons.org/publicdomain/zero/1.0/).

docs/bootstrap-governance/meps.md

@@ -0,0 +1,89 @@
+(governance:meps)=
+# MyST Enhancement Proposals
+
+Because the MyST specification has many interior and exterior stakeholders, we use a more formal and structured process around changing the specification.
+These are called **MyST Enhancement Proposals (MEPs)**.
+This process is encoded in `executablebooks/myst-enhancement-proposals` and described briefly below.
+
+## Goals of the MEP process
+
+- **Formal without being oppressive**. Provide slightly more structure than our organizational policy, to account for the fact that MEPs have many more stakeholders and decision-makers. However keep it as simple as possible to avoid overly-complex discussion that leads to frustrating and inefficient decision-making.
+- **Make the process inclusive**. Ensure a process for discussion and deciding that is inclusive and that encourages productive discussion from many parts of the project.
+- **Make the process efficient**. Ensure that there is enough information, and with the right structure, to have focused asynchronous discussion that leads to a decision-making cadence that is sustainable for the project.
+- **Design for many stakeholders**. Ensure that the specification evolves in a way that benefits our major stakeholders, and that is not unintentionally over-fit to the perspective of only a subet of the Executable Books community.
+
+## The MEP process
+
+1. **Open an issue in `myst-enhancement-proposals`** that describes the enhancement you'd like to make. The goal of the issue is to help others understand your idea and get informal alignment around it, and to decide if it is well-suited for the MEP process[^when-mep]. _MEPs should ideally have at least two, and ideally 3-4 co-authors from different organizations._
+2. **Make a proposal via a PR to `myst-enhancement-proposals`**. Use a markdown template to structure your proposal. The `status` should initially be set to `Draft`. Here's a proposed template:
+
+   ```
+   ---
+   mep:
+      id: <NNNN - Add when this MEP becomes Active>
+      created: <yyyy-mm-dd - date MEP is active>
+      authors:
+        - <authors' real names, optional github handle>
+      status: <Draft | Active | Accepted | Not Accepted>
+      discussion: <URL of canonical location for discussion>
+   ---
+   # <title here>
+
+   ## Context
+   
+   <!-- provide context needed to understand this proposal. Describe the problem with MyST's current syntax or behavior. -->
+   
+   ## Proposal
+   
+   <!-- describe your proposed change to syntax in concrete terms. Include a layperson's description of this change if relevant. -->
+   
+   ## Examples
+   
+   <!-- provide examples of what this change would look like in the real world (e.g., raw MyST and rendered output). -->
+   
+   ## UX implications & migration
+   
+   <!-- describe how this would improve the UX or functionality of MyST markdown. Describe any deprecations or syntax migration steps that would be needed. -->
+   
+   ## Questions or objections
+   
+   <!-- as conversation takes place, list anything that is needed to be resolved and provide links to the conversation where this happened. -->
+   
+   ## References
+   
+   <!-- reference other examples you're using for inspiration or to help others learn and understand the proposal. -->
+   ```
+4. **Discuss and iterate**. Invite discussion from others in the community. Incorporate new ideas as individuals (particularly core team members) raise objections or make suggestions.
+   % TODO: Define guidelines for considerations to take during discussion, such as implementation feasibility.
+   % TODO: Define policy around what happens if an implementation _cannot_ implement something that has already been merge into the spec.
+   % one suggestion here: https://github.com/executablebooks/meta/pull/843#issuecomment-1274555428
+5. **Activate decision making**. Once the proposal has stabilized and the author wishes to move forward, do the following:
+   - In the MEP frontmatter, set the status as `Active` and add an incremental MEP number (e.g. `id: 0002`). The MEP should no-longer change substantially.
+   - **The Core Team** should review the MEP and approve if they wish to accept it.
+     - To approve, click `Approve` the GitHub Pull Request UI.
+     - To request blocking changes, then click `Request Changes` in the GitHub UI.[^blocking]
+   - A MEP may be accepted when all of the following conditions are met:
+     - More than five (5) weekdays have passed since the proposal was marked as `Active`.
+     - At least two `PR Approvals` from **core team members**.
+     - No `Request Changes` from a core team member.
+   - If the MEP is accepted:
+     - Update its status metadata to `Accepted` and merge the PR.
+     - Once a PR is merged, it closes the issue and a decision has been made.
+     - The changes in the MEP then become "part of the myst spec" via a Pull Request to `myst-specification` that anyone is welcome to implement.
+   - If there are unresolved objections (via `Request Changes` to the PR)
+     - The MEP author may restart the voting process after incorporating feedback to resolve the objection, **or** ask the Steering Council to follow the same [decision-making process used for team policy](governance:policy-decision).
+
+
+[^when-mep]: Below is example text to provide guidance in when to use the MEP process.
+
+    ```
+    ## When should I open a MEP?
+
+    The goal of Enhancement Proposals are to align the team on major strategic decisions about MyST Markdown, and to formally record a decision. When deciding whether to propose a MEP, consider whether the importance or complexity of the topic is worth the extra overhead of the MEP process. Ultimately, the most important thing is that we follow principles of open and inclusive discussion, iteration and collaborative writing, and making decisions explicit.
+
+    As a guide, below are examples of topics that warrant a MEP:
+
+    - Changing or extending the syntax or major functionality of MyST.
+    - Defining high-level strategy and vision for the language
+    - Amending the MEP process itself
+    ```