Skip to content

Latest commit

 

History

History
291 lines (177 loc) · 16.6 KB

ReleaseGuidelines.md

File metadata and controls

291 lines (177 loc) · 16.6 KB
Raw

MDS Release Guidelines

MDS will see regular updates and new releases. This document describes the general guidelines around how and when a new release is cut.

Table of Contents

Versioning

MDS uses Semantic Versioning. Each release is associated with a git tag of the form X.Y.Z.

Given that MDS is stabilizing under MAJOR version 0.x right now, it should be assumed that MINOR version increments (e.g. 0.2.0 to 0.3.0) are equivalent to MAJOR version increments and may contain breaking changes.

Breaking vs. non-breaking changes

Since MDS is used by a broad ecosystem of both API consumers and implementers, it needs a strict definition of what changes are “non-breaking” and are therefore allowed in PATCH releases.

In the MDS spec, a breaking change is any change that requires either consumers or implementers to modify their code for it to continue to function correctly.

Examples of breaking changes include:

  • Adding or removing a required endpoint or field
  • Adding or removing a request parameter
  • Changing the data type or semantics of an existing field, including clarifying previously-ambiguous requirements

Examples of non-breaking changes include:

  • Adding or removing an optional endpoint or field
  • Adding or removing enum values
  • Modifying documentation or spec language that doesn't affect the behavior of the API directly

One implication of this policy is that clients should be prepared to ignore the presence of unexpected fields in responses and unexpected values for enums. This is necessary to preserve compatibility between PATCH versions within the same MINOR version range, since optional fields and enum values can be added as non-breaking changes.

Ongoing version support

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

Project Meetings

  • Web conference work sessions will posted to the MDS-Announce mailing list and on the MDS wiki. Each working group typically meets every two weeks.

  • The meeting organizer can use the meeting template to prepare for project meetings. Use the template markup code to create the next scheduled wiki meeting page before the meeting. Include the how to join the meeting and agenda details. Posting the agenda before the meeting has the added benefit that project contributors can propose agenda items.

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.

  • working group steering committees - Review changes when consensus cannot be reached and make final release decision about what changes should be included in a release.

See the MDS wiki for additional information on the working groups.

Schedule

MDS operates on an approximately twelve-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 twice per year. The release cycle is broken down as follows:

Weeks 1-3: Proposals

Contributors submit proposals for inclusion in the release cycle in the form of pull requests and issues tagged. If known, note what release you intended a proposal for in its description. Maintainers will tag appropriate pull requests and issues with the Milestone for the upcoming release. Proposals should come with enough explanation to allow all stakeholders to understand intent and implementation strategy.

Weeks 4-9: 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 9, all active proposals must be in the form of a pull request. Proposals can be withdrawn or split apart for inclusion in future releases.

Weeks 10-11: Decision making

These weeks will start with an 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.

During this period, the working group steering committees will review all items for which consensus was not reached and decide on a final release plan. Any remaining approved pull requests will be merged, and a maintainers or working group steering committees will open a pull request containing release notes for the proposed release.

Week 12: Release

Documentation will be updated, release notes will be merged, a tag will be created and master updated to point to it, and the new version will be formally released. See Release Checklist for details about the release process.

Approval by the Open Mobility Foundation

Once a release is finalized by the working groups it will be considered a "release candidate" until it has been approved as an official deliverable by the Open Mobility Foundation. The OMF bylaws refer to this as a "Working Group Approved Deliverable (WGAD)."

The process for full OMF approval is detailed in Section 5.4 of the OMF bylaws, the latest version of which can be found here. In summary:

  1. The release candidate/WGAD will be provided to the OMF Technology Council for review and comment at least 75 days prior to the desired date of board approval.

  2. The Technology Council will issue a report and/or recommendation for the Board of Directors within 60 days.

  3. The Board of Directors will have a minimum of 30 days to review the Technology Council recommendation before taking a vote on the release candidate/WGAD.

  4. Upon approval by the Board of Directors, the release will become an official deliverable of the OMF and will be marked as such in GitHub and on the OMF web site.

While it is the intent of the OMF to have concerns, questions, and issues addressed during the regular working group release process, it is possible that the Technology Council or Board of Directors may request modifications to a release candidate/WGAD prior to official approval. If this situation occurs, the release candidate will be sent back to the working group(s) for additional changes after which it can be resubmitted to the Technology Council and Board of Directors.

Communication and Workflow

The release announcements and process schedule will be communicated via MDS-Announce mailing list. 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 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

The branching strategy we describe here is intended to handle ongoing maintenance changes in parallel with features for new releases.

Primary branches

At a high-level, there are two primary branches:

  • master represents the latest release of MDS. It's only updated as part of the release process, and no pull requests should be based on or target it.

  • dev contains all work that has happened since the last release, including both breaking and non-breaking changes.

Feature branches

All development on changes to MDS should happen in branches cut from dev (with the exception of hotfixes to release branches, described below). When your work is ready for review, submit a PR against dev, ideally with any merge conflicts already resolved. dev serves as the collection point for all new feature work.

Release branches

Whenever a MINOR version is released, a release branch will be created from dev to track any changes that should be included in subsequent PATCH versions. For example, at the time 0.4.0 is released, a branch called 0.4.x will be created that initially points to the same commit as the 0.4.0 tag.

Release branches can be updated in two ways:

  • When a non-breaking change has been merged to dev, a maintainer will usually backport it onto the newest release branch. This can be skipped if the change isn't relevant to the release branch (e.g., because it modifies language that was added after the last MINOR release) or if there are no plans to make another PATCH release with the same MINOR version.

  • If a change needs to be made to spec language that exists in a release branch but is no longer relevant in dev, the contributor should create a feature branch based on the release branch and open a PR targeting the release branch directly. For example, if an endpoint was removed in 0.3.0 but needs to be modified for a 0.2.1 PATCH release, the contributor would create a PR based on the 0.2.x release branch.

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), no further changes will be made to the outgoing series (0.2.x, in this case).

Backporting changes

When non-breaking changes are merged to dev, it's generally necessary for a maintainer to backport these changes to the newest release branch so that they'll be included in any subsequent PATCH releases. There are a couple of different ways to do this:

  • If the changes can be applied to the release branch without significant editing, the maintainer can use git cherry-pick to copy the changes from dev into the release branch (assuming the SHA of the merge commit on dev was b70719b):

    git fetch
git checkout 0.3.x
git pull
git cherry-pick -m 1 b70719b
git push

    Note that the -m 1 option is unnecessary if the PR was merged with the "Squash and merge" option instead of creating a merge commit.

  • If backporting the change needs significant manual work (for example, if there were other changes to the relevant part of the spec in the last MINOR version), the maintainer can open a new PR for the backport targeting the relevant release branch.

    First, create a branch containing the backported change (again, assuming the SHA of the merge commit was b70719b):

    git fetch
git checkout 0.3.x
git pull
git checkout -b backport-helpful-change-to-0.3.x
git cherry-pick -m 1 b70719b
# Do any manual work needed to integrate the changes
git push -u origin backport-helpful-change-to-0.3.x

    Next, create a PR with the release branch (in this case, 0.3.x) as its base. Once that PR has been approved, merge the PR into the release branch as usual.

Release Checklist

The following steps must be followed for every release of MDS:

  1. Ensure the Milestone for this release is at 100%.

  2. Update the schema version regex.

  3. Run the schema generator to ensure the schema files are up to date:

    cd generate_schema/
pipenv run python generate_provider_schema.py

  4. Open a PR against dev that updates ReleaseNotes.md using the following format:

    ## 1.2.3

> Released yyyy-MM-dd

High level summary of the release.

* Specific change referencing a PR [#555](https://github.com/openmobilityfoundation/mobility-data-specification/pull/555)

* Another change summary referencing a PR [#777](https://github.com/openmobilityfoundation/mobility-data-specification/pull/777)

    The description of this PR should include a link to a GitHub compare page showing the changes that will be included in the release. This URL depends on the type of release:

    In the case of a new MINOR version, allow a minimum of 24 hours for community discussion and review of the current state of the release.

  5. Once the PR has been sufficiently reviewed, merge it into dev.

  6. Create a tag for this release on the tip of dev (for MINOR versions) or the relevant release branch (for PATCH versions). For example, for 0.5.0:

    git fetch
git checkout origin/dev
git tag 0.5.0
git push --tags

    Or for 0.4.2:

    git fetch
git checkout origin/0.4.x
git tag 0.4.2
git push --tags

  7. If this release is a MINOR version, create a new release branch. For example, if you've just created the 0.5.0 tag:

    git push origin 0.5.0:0.5.x

  8. Unless this is a maintenance release on an older branch (for example, releasing 0.3.2 after 0.4.0 has already come out), update master to point to the new tag:

    git checkout master
git reset --hard 0.5.0
git push --force origin master

  9. Publish a new Release in GitHub for the tag you just pushed. Copy in the release notes created earlier.

  10. Post a release announcement to mds-announce, copying the release notes created earlier and linking to the GitHub release.

    From:    mds-announce@groups.openmobilityfoundation.org
To:      mds-announce@groups.openmobilityfoundation.org  
Subject: MDS 1.2.3 Release  

MDS 1.2.3 has been released.

<release notes>

<link to GitHub release>