Development ¶
Contributing to TIDES ¶
Thank you for contributing to the TIDES Project. This document outlines the process for contributing to the project and documents the governance roles and approach for decision-making. Where TIDES Governance and this document differ, the TIDES Governance shall take precedence.
Becoming a TIDES Contributor ¶
As defined in the TIDES Governance, a TIDES-Contributor has the rights to:
- Create issues, discussions, and pull requests in the TIDES repository.
- Vote in decisions on changes to the TIDES spec and other aspects of TIDES.
These roles and responsibilities are further detailed in the TIDES Governance and documents linked to from it.
Individuals may request to be a Contributor by completing the registration formthat includes acknowledgement of the Contributor Agreement and Code of Conduct.
How to Contribute ¶
- Become a TIDES Contributor
- Follow setup instructions if you’d like to contribute code or provide code reviews.
- Offer to help research an issue
- Offer to help resolve an issue with a pull-request
- Offer to review a pull-request
Warning
By making any contribution to the projects, contributors self-certify to the Contributor Agreement.
Setup ¶
- Make sure you have a GitHub account.
- Make sure you have git, a terminal (e.g. Mac Terminal, CygWin, etc.), and a text editor installed on your local machine. Optionally, you will likely find it easier to use GitHub Desktop, an IDE instead of a simple text editor like VSCode, Eclipse, Sublime Text, etc.
- Clone the repository locally. Non-registered contributors should fork the repository first, since they will be unable to push branches directly to the main repository.
- Install development requirements packages
pip install -r requirements.txt
or in a virtual environment.
Using a virtual environment
It is often helpful to install requirements for vairous projects inside a virtual environment rather than in your main python installation. Some virtual environments to consider include: conda
,pipenv
,poetry
, and rye
.
Contribution Workflow ¶
- Create a feature branch to work on a new issue (or checkout an existing one where the issue is being worked on).
- Make your changes.
- Run
tests/test_local_spec
script to check and fix formatting, validate profile and schemas with frictionless and with each other, and confirm that documentation can be built locally. - Run
tests/test_samples_to_local
script to check if samples conform to any changes to the spec. - Commit your work in
git
push
your changes to Github and submit apull request
Create a feature branch on a clone of tides-transit/TIDES
, not a fork
If you have the permissions (which you should if you are a TIDE Contributor), you should complete your work on a feature branch from a clone of the main TIDES repository (tides-transit/TIDES
) rather than a fork of it (e.g. my-github-handle/TIDES
) so that when you submit a pull request the continuous integration tests will have the right permissions to run.
Issues ¶
Create issues to start discussion on a new topic. If the issue is associated with a pull request, be sure to link the two. There are shortcuts here
Pull Requests ¶
Use the following guidance in creating and responding to pull requests
- Keep pull requests small and focused. One issue is best.
- Link Pull Requests to Issues as appropriate.
- Complete the pull request template as best you can.
- In order to run all GitHub Actions automations, contributors with adequate permissions (i.e. Registered Contributors) should submit pull requests from a branch on the main repo, rather than from a fork.
If you worked from a fork
If you worked from a fork of the TIDES/tides-transit
repo instead of a feature branch of a clone of the TIDES/tides-transit
repo, you will not have the right permissions to run the continuous integration tests when you submit a pull request. To remedy, please push the branch of your local fork to a feature branch of the main repository:
git remote add upstream git@github.com/TIDES-transit/TIDES.git
git push upstream <my-feature-branch-name>
…and now you should be able to submit a pull request from that feature branch which should have the permission to run the continuous integration tests.
Run into a permissions issue with that command? Make sure you a registered contributor and that you have accepted the resulting invitation to join the tides-transit
team on Github.
Commits ¶
Use the following guidance for commits
- Provide a short, clear title. Capitalize. No period at the end
- Wrap the body of text at 72 characters
Continuous Integration / Continuous Deployment ¶
We leverage Github Actions workflows to flag potentially erronious contributions and build, preview and deploy documentation that is in sync with the schema definition files.
Workflows are defined in /.github/workflows/
include the following:
File | Description |
---|---|
validate_package_schema.yml |
Validates Data Package definition |
validate_table_schemas.yml |
Validates Schema Files |
docs.yml |
Builds and deploys documentation |
docs.yml
Process
Documentation ¶
The documentation for the TIDES specification is available at https://tides-transit.github.io/TIDES/ This site is automatically recreated each time a change is made to the specification.
More information about updating and building TIDES documentation…
TIDES Contributor License Agreement ¶
By making any contribution to the projects, contributors self-certify to the the TIDES Contributor Agreement.
License to Use ¶
The TIDES specification is licensed under the Apache License 2.0 (code) and Creative Commons Attribution 4.0 (sample data, specification, and documentation) as defined in
Project Governance ¶
The TIDES Project Governance and the roles within are detailed in the TIDES-governance documentation.
GitHub Access Levels ¶
Role | Access Level |
---|---|
Board | Admin |
Program Manager | Admin |
Board Coordinator | Write |
Manager | Write |
Contributor Group | Write |
Stakeholder | Read/Create Issues |
Review and Approval Process ¶
The TIDES Board has final approval of all normative changes changes to the specificaiton and project governance. All Contributors are permitted and encouraged to discuss and comment on issues and pull requests and make recommendations for changes to the specification. Contributions made as a pull request by Contributors which do not make any changes to the /spec
or /docs/governance
directories may be approved by a another Contributor if it passes the continuous integration tests.
Following v1.0, TIDES will adhere to this change management and versioning policy.
TIDES Code of Conduct ¶
Contributors to the TIDES Project are expected to read and follow the code of conduct for the project.