Skip to content

Process for Changes

Jump to bottom
haeckerbaer edited this page Feb 25, 2020 · 11 revisions

Table of Contents

What to do, if you have an idea for a change
How to prepare a change request
Preparing a pull request
Process for the integration of a pull request
Documentation typos etc.
Minor releases and major releases
Keeping the documentation and the XSD in sync
Continuous integration with TravisCI

What to do, if you have an idea for a change

Use the template to fill in a change request and send it by eMail to us. If you already have a pull request for the changes in the schema, even better. But perhaps you want to first consult with the SIRI WG, if the change has a chance to be accepted.

We don't use the issues capabilities of GitHub currently.

How to prepare a change request

  • Copy the template: https://public.3.basecamp.com/p/nK4pAcR1yqsY6CDm7drHZmS3
  • Make sure to check, that the change is not already in our pipeline (https://public.3.basecamp.com/p/pwE1d4xLg73t1nMHrT6wLWEJ)
  • Only pack one change in one pull request or CR document.
  • Send it to us (christophe.duquesne@aurigetech.com; bruns@vdv.de; adrian.aeschbacher2@sbb.ch)
  • Preferably we would like to get a full pull request that also works on the official SIRI examples and possibly new ones from you.
  • Open an issue (official SIRI CR template) if you can only describe the problem. We again prefer a detailed proposal for the solution. However, sometimes an issue needs to be discussed first in an early stage, then an issue is the right way to start the conversation. Copy the structure of an existing issue or use the official SIRI CR template.
  • As we need to synchronize the documentation with the XSD, we will still need an issue (that includes the needed changes in the documentation). At least a filled in CR template must be added in this issue. Additional files/data can be added if necessary.
  • Reference the pull request in the issue and vice versa.

Preparing a pull request

  • Read: https://yangsu.github.io/pull-request-tutorial/
  • Make sure, that the xsd is validating after your changes
  • Make sure to have used the latest version for your changes.
  • Make sure the examples are also still valid. We will not accept pull requests that do not do that and we will test automatically.
  • Use xmllint for pretty-printing it in the way we need (we will automatize this step very soon)

Process for the integration of a pull request

  • We will link the CR document in basecamp with the pull request (simple reference by link).
  • Travis will validate the requests by checking the schemas, formatting if necessary and testing the official SIRI examples.
  • The different members of the SIRI subgroup will "vote" on the pull request. They can add comments and add themselves as reviewers to accept the changes or request additional changes.
  • If necessary an update must be provided by the author. This can also concern the issue in the documentation.
  • If the reviews are finished and the changes accepted someone of the core group will merge the request into the integration branch and update the documentation of the standard (in Basecamp) at the same time. The documentation change is noted.
  • The CR master list (excel) in basecamp must be updated afterwards.
  • To avoid editing conflicts in the document, its name is updated with the suffix "_checkout", whenever it is edited by somebody. A note indicates the name of the editor.

Documentation typos etc.

Minor releases and major releases

  • After a given number of change requests a new version is formed
  • The integration branch is merged with the master branch.
  • Minor releases will be shown with a new letter (e.g. v2.0o). This should be non-breaking changinges.
  • A version number in the second number is still minor. There should mainly be extensions and things that can easily be adapted like enums (e.g. v.2.1a)
  • A major release with a new version (e.g. v3.0a) contains breaking changes.

Keeping the documentation and the XSD in sync

For copyright reasons the full document of the standard cannot be put here. However, we want all changes in the XSD also to be in the document at the same time. This means that a pull request is only merged, when at the same time the document(s) are updated. In case of supporting lists, they will be in the repository as well and can be part of a pull request.

Continuous integration with TravisCI

TravisCI is used for automatic checks, formatting and tests of examples: https://travis-ci.org/

When a branch is submitted as pull request, TravisCI runs simple checks on the schema (with the new changes included) and indicates whether the changes are valid. A branch can only be merged if TravisCI approves the changes. Travis will also occasionally correct the formatting and commit its updates back to the github repo.

Clone this wiki locally