Release process and contribution guidelines

CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# MDS Contributor Guidelines
+MDS is an evolving specification with a regular release cycle. Please review the [MDS Release Guidelines](ReleaseGuidelines.md) to understand the release process.
+
+## Who can contribute
+MDS is an open specification and anyone can contribute to its development. Because MDS supports a growing ecosystem of mobility services, policies, and tools, there are some key stakeholders whose participation is particularly encouraged:
+
+* **Public agencies:** As licensing authority and regulator, public agencies are the ultimate customers for MDS and the data flowing through it. The public agency role is to ensure that MDS effectively supports program management and offers a flexible foundation for policy implementation. Public agencies of all levels of technical capacity are encourage to participate in the evolution of MDS, whether by submitting pull requests and issues, or simply by providing feedback during release cycles.
+
+* **Mobility Service Providers:** Providers are often required to implement MDS in order to comply with permitting requirements for their services. Providers can inform the development of MDS with real-world operating experience and to offer input on specification design that maximizes data quality, reliability, and utility.
+
+* **Public agency software partners:** Serve as a key bridge between public agencies and mobility service providers by offering tools that turn MDS data into useful insights. The public agency software partners help ensure that MDS will enable real-world product development, reflects the needs of their public agency customers, and encourages private investment in the MDS ecosystem.
+
+## How to contribute
+Contributions should be offered through GitHub issues and pull requests. Please review the [MDS Release Guidelines](ReleaseGuidelines.md) for details on the release process, schedule, and communications channels.
+
+In general, you may open an issue or make a pull request at any time. Once the issue or pull request is associated with a particular Milestone, it will be included for review within the process for that release.
+
+## What belongs in MDS
+MDS is a tool to facilitate data exchange between mobility service providers, public agencies, and public agency software partners. Although providers are often required to support MDS as part of mobility permits or policies, MDS is intended as a neutral mechanism for information exchange. It is not intended to force or foreclose any specific policy options that a public agency may choose to pursue.
+
+## Code of Conduct
+To encourage participation by any and all interested people, we aim to create an open and welcoming environment for contributors. We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+**Examples of behavior that contributes to creating a positive environment include:**
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members

ReleaseGuidelines.md

@@ -1,12 +1,16 @@
 # MDS Release Guidelines
 
-MDS will see periodic updates and new [releases][mds-releases] from time to time. This document describes the general guidelines around how and when a new release is cut.
+MDS will see regular updates and new [releases][mds-releases]. This document describes the general guidelines around how and when a new release is cut.
 
 ## Table of Contents
 
 * [Versioning](#versioning)
+* [Release Process](#process)
+  * [Goals](#goals)
+  * [Roles](#roles)
+  * [Schedule](#schedule)
+  * [Communication and Workflow](#communication-and-workflow)
 * [Branch Mechanics](#branch-mechanics)
-* [Schedule](#schedule)
 * [Checklist](#release-checklist)
 
 ## Versioning
@@ -19,7 +23,70 @@ Given that MDS is stabilizing under MAJOR version `0.x` right now, it should be
 
 At this early stage, MDS will be moving relatively quickly with an eye toward stabilization rather than backwards-compatibility.
 
-For now, MDS will maintain *two concurrent (MINOR) versions* (e.g. if `0.3.0` were the current verison, the `0.2.x` series would continue to receive maintenace in addition to `0.3.x`).
+For now, MDS will maintain *two concurrent (MINOR) versions* (e.g. if `0.3.0` were the current version, the `0.2.x` series would continue to receive maintenance in addition to `0.3.x`).
+
+
+## Release Process
+The sections below define the release process itself, including timeline, roles, and communication best practices.
+
+> **The process defined below currently being piloted with the MDS `provider` API only. Proposed changes to the `agency` API will be continue to be reviewed on an ad hoc basis.**
+
+>**It is our intent to maintain a level of coordination between the technical direction of `agency` and `provider`. As such, proposed changes to either API will be reviewed to ensure they do not create unnecessary duplicative functionality, introduce confusion about which API should be used for a given purpose, or prevent the reconciliation of data between the two APIs (for example: using data from `provider` to cross-validate data received via `agency`).**
+
+### Goals
+
+* _Fast, regular releases to support rapid evolution of MDS_
+
+* _Consensus-oriented with clear decision making process when consensus can't be reached_
+
+* _Encourage involvement from all stakeholders, especially public agencies_
+
+* _Frequent stakeholder communication on GitHub, web conference, and in-person_
+
+* _Regular review of release process to ensure it is serving the needs of the community._
+
+
+### Roles
+* **contributors** - Anyone making pull requests, opening issues, or engaging in technical discussion around implementation of features.
+* **maintainers** - Project maintainers have commit privileges in the main MDS repository and are responsible for implementing changes such as merging of pull requests and the creation of release branches.
+* **release partner** - Review changes when consensus cannot be reached and make final release inclusion recommendations to maintainers for approval.
+
+As of March 2019, LADOT and the City of Santa Monica are the project maintainers and Remix is the release partner.
+
+### Schedule
+
+MDS operates on a six-week release cycle for both major updates (0.x) and patches (0.x.y). In general, major updates (0.x) are expected no more than once per quarter. The release cycle is broken down as follows:
+
+**week 1 - proposals**
+
+Contributors submit proposals for inclusion in the release cycle in the form of pull requests and issues tagged with the Milestone for the upcoming release. Proposals should come with enough explanation to allow all stakeholders to understand intent and implementation strategy. |
+
+**weeks 2-4 - consensus building, refinement, and implementation**
+
+Contributors will provide feedback on proposals. Where possible, discussion will happen via GitHub. Weekly calls will support dialog around more complex or controversial issues. By the end of week 4, all active proposals must be in the form of a pull request. Proposals can be withdrawn or split apart for inclusion in future releases.
+
+**week 5 - decision making**
+
+The week will start with an in-person/web conference work session for all contributors to review and discuss current proposals. Goal is to achieve consensus where possible, or to clearly articulate areas of disagreement where not. Minor changes may be accepted at this stage if they bring contributors to consensus.
+
+At the conclusion of week 5, release partner will review all items for which consensus was not reached and provide a recommended release plan to maintainers for approval. Any remaining approved pull requests to `dev` are merged or the release branch as necessary.
+
+**week 6 - release**
+
+​Documentation will be updated, a release branch will be created if necessary, changes will be merged into `master`, and new version will be formally released.
+
+### Communication and Workflow
+The release annoncements and process schedule will be communicated via [`mds-announce`][mds-announce] Google Group. People wishing to stay informed should join the group for updates. Timing of web conference and in person work sessions will be communicated via mds-announce as well.
+
+The following best practices are intended to create clarity around each release cycle:
+
+* Categorize issues and PRs under an associated [Milestone][mds-milestones] for the release
+
+* Assign a due date for said Milestone that aligns with proposed release date
+
+* Pull requests and release notes should include a summary of the major changes / impacts associated with the change or release
+
+* Proposed changes should come in the form of PRs to give the community ample awareness and time for feedback
 
 ## Branch Mechanics
 
@@ -45,24 +112,9 @@ This *release branch* represents the current state of that release series. All m
 
 When a PATCH release is ready (e.g. `0.2.0` to `0.2.1`), the release branch (e.g. `0.2.x`) is merged to `master` (to make the release official) and `dev` is rebased onto `master` (to ensure the patch is incorporated with any new work).
 
-As stated earlier, at this time MDS will maintain *two concurrent MINOR versions*. This means that when a MINOR release is made (e.g. `0.4.0`), work on the outgoing series (`0.2.x`, in this case) ceases and its release branch is removed.
-
-## Schedule
-
-MDS does not currently define a set release cadence or schedule. That being said, a MDS
-release should not surprise anyone that wishes to be informed. To that end, releases will always:
-
-* Categorize issues and PRs under an associated [Milestone][mds-milestones]
-
-* Assign a due date for said Milestone that is *at least 24 hours ahead of planned release*
+Breaking changes should always be merged to develop. These may be merged at any time and will be incorporated into the next minor release. For non-breaking changes, these should either be merged to develop if the next release is a minor release, or to the appropriate release branch if the next version is a patch release. During each cycle, we merge changes to both dev and 0.n.x branches, so breaking changes can be proposed and worked on at any time
 
-* Include a summary of the major changes / impacts associated with the release, if any
-
-* Be PR-driven, to give the community ample awareness and time for feedback
-
-* Be announced on the [`mds-announce`][mds-announce] Google Group
-
-More detail on this can be read in the Release Checklist below.
+As stated earlier, at this time MDS will maintain *two concurrent MINOR versions*. This means that when a MINOR release is made (e.g. `0.4.0`), work on the outgoing series (`0.2.x`, in this case) ceases and its release branch is removed.
 
 ## Release Checklist
 
@@ -154,4 +206,4 @@ The following steps **must** be followed for **every** release of MDS:
 [mds-releases]: https://github.com/CityOfLosAngeles/mobility-data-specification/releases
 [mds-releases-new]: https://github.com/CityOfLosAngeles/mobility-data-specification/releases/new
 [mds-tags]: https://github.com/CityOfLosAngeles/mobility-data-specification/tags
-[semver]: https://semver.org/
+[semver]: https://semver.org/