Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Release process and contribution guidelines #264

Merged
merged 10 commits into from
Mar 18, 2019
30 changes: 30 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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
77 changes: 64 additions & 13 deletions ReleaseGuidelines.md
Original file line number Diff line number Diff line change
@@ -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)
* [Branch Mechanics](#branch-mechanics)
* [Schedule](#schedule)
* [Release Process](#process)
* [Goals](#goals)
* [Roles](#roles)
* [Schedule](#schedule)
* [Communication and Workflow](#communication-and-workflow)
* [Checklist](#release-checklist)

## Versioning
Expand All @@ -19,7 +23,7 @@ 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`).

## Branch Mechanics
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jfh01 can you add some language about how to merge breaking requests (ie, stuff that is staged for a 0.x.0 release) versus stuff that is non-breaking (ie, stuff staged for a 0.3.x) release. I don't wanna end up having to do all breaking changes in a 6 week cycle.

Copy link

@ccolgrove ccolgrove Mar 15, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hunterowens how about this:

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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good.
Would add at the end

"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"


Expand All @@ -45,24 +49,71 @@ 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).

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

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
## 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**

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:
​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.

* Categorize issues and PRs under an associated [Milestone][mds-milestones]
### 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.

* Assign a due date for said Milestone that is *at least 24 hours ahead of planned release*
The following best practices are intended to create clarity around each release cycle:

* Include a summary of the major changes / impacts associated with the release, if any
* Categorize issues and PRs under an associated [Milestone][mds-milestones] for the release

* Be PR-driven, to give the community ample awareness and time for feedback
* Assign a due date for said Milestone that aligns with proposed release date

* Be announced on the [`mds-announce`][mds-announce] Google Group
* Pull requests and release notes should include a summary of the major changes / impacts associated with the change or release

More detail on this can be read in the Release Checklist below.
* Proposed changes should come in the form of PRs to give the community ample awareness and time for feedback

## Release Checklist

Expand Down Expand Up @@ -154,4 +205,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/