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.

Sign up for GitHub

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

Contributing updates #173

Merged
merged 2 commits into from
Aug 2, 2021
Merged

Contributing updates #173

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
16a3b17
update contributing, esp. governance
philvarner Jul 14, 2021
24df116
openapi
philvarner Aug 2, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 36 additions & 37 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,16 @@
# STAC API Development & Release Process

## Contributing

Anyone building software that catalogs imagery or other geospatial assets is welcome to collaborate.
Our goal is to be a collaboration of developers, not [architecture astronauts](http://www.joelonsoftware.com/articles/fog0000000018.html).
Pull Requests are the primary method of contributing to the spec itself, and everyone is welcome to submit
changes. Suggestions for changes to the core will be taken with higher priority if a clear implementation
of STAC API has been built that can highlight the problem.

The best way to contribute is to try to implement the specification and give feedback on what worked
well and what could be improved. Any proposed changes to the specification should be done as pull requests. Ideally a
proposed change would also update all of the examples, but for now that is not required - the team
can validate and update all examples before a release. But it is recommended to update at least a
couple examples to reflect the change.
We consider everyone using the specification to catalog their data to be a 'contributor', as STAC is
really about the end result of more interoperable data, not just creating a spec for the sake of it.
So if you want to help then the best thing you can do is make new catalogs or build software that uses
the spec. And please do give us feedback. The best place to do so is on our
[gitter channel](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby). If you are interested in helping
but aren't sure where to, then see the [stac-ecosystem](https://github.com/stac-utils/stac-ecosystem) repo
for ideas on projects to advance STAC.

## Development Process

Expand All @@ -25,50 +26,50 @@ examples.
### Submitting Pull Requests

Any proposed changes to the specification should be done as pull requests. Please make these
requests against the [`dev`](https://github.com/radiantearth/stac-api-spec/tree/dev) branch (this will
requests against the [dev](https://github.com/radiantearth/stac-api-spec/tree/dev) branch (this will
require you to switch from the default of 'master', which we keep so it displays first).

Creating a Pull Request will show our PR template, which includes checkbox reminders for a number
of things.

- Adding an entry the [CHANGELOG](CHANGELOG.md). If the change is more editorial and minor then this
is not required, but any change to the actual specification should definitely have one.
- Base the PR against dev, as mentioned above - even if the branch was made off of dev this reminds
you to change the base in GitHub's PR creation page.
- Highlight if the PR makes breaking changes to the specification (in beta there can still be
select breaking changes, but after 1.0 this will change)
of things, including adding an entry the [CHANGELOG](CHANGELOG.md) and making the PR against the `dev`
branch.

All pull requests should submit clean markdown, which is checked by the continuous integration
system. Please use `npm run check-markdown` locally, as described in the [next section](#using-check-markdown-locally),
system. Please use `npm run check` locally, as described in the [next section](#check-files),
to ensure that the checks on the pull request succeed. If it does not then you can look at the
mistakes online, which are the same as running `check-markdown` locally would surface.
mistakes online, which are the same as running `npm run check` locally would surface.

All pull requests that modify or create JSON examples should use [JSON
formatter](https://jsonformatter.org/) to keep files consistent across the repo.
All pull requests that modify or create JSON schema files or examples should use
[JSON formatter](https://jsonformatter.org/) to keep files consistent across the repo.

All pull requests additionally require a review of two STAC core team members. Releases are cut
from dev to master (and require 3 approvals).

### Using check-markdown locally
### Check files

The same check-markdown program that runs as a check on PR's is part of the repo and can be run locally.
To install you'll need npm, which is a standard part of any [node.js installation](https://nodejs.org/en/download/).
Alternatively, you can also use [yarn](https://yarnpkg.com/) instead of npm. In this case replace all occurrences of
`npm` with `yarn` below.
The same check-markdown and check-examples programs that runs as a check on PR's is part of the repo and can be run locally.
Copy link
Collaborator

Choose a reason for hiding this comment

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

I don't think 'check-examples' is part of the api spec repo? Running 'check' seems to use check-markdown and check-openapi. Should update this to explain what check-openapi does. Running it right now seems to raise some warnings, so we should probably try to fix those:

/Users/cholmes/Repos/stac-api-spec/fragments/filter/cql.yml
 16:9  warning  oas3-parameter-description  Parameter objects should have a `description`.  components.schemas.booleanValueExpression.oneOf[3]
/Users/cholmes/Repos/stac-api-spec/fragments/filter/openapi.yaml
  10:9  warning  operation-description  Operation `description` must be present and non-empty string.  paths./.get
  10:9  warning  operation-tags         Operation should have non-empty `tags` array.                  paths./.get
 29:11  warning  operation-tag-defined  Operation tags should be defined in global tags.               paths./queryables.get.tags[0]
  42:9  warning  operation-description  Operation `description` must be present and non-empty string.  paths./collections/{collectionId}.get
  42:9  warning  operation-tags         Operation should have non-empty `tags` array.                  paths./collections/{collectionId}.get
 74:11  warning  operation-tag-defined  Operation tags should be defined in global tags.               paths./collections/{collectionId}/queryables.get.tags[0]

To install you'll need npm, which is a standard part of any [node.js installation](https://nodejs.org/en/download/).
Alternatively, you can also use [yarn](https://yarnpkg.com/) instead of npm. In this case replace all occurrences of `npm` with `yarn` below.

First you'll need to install everything with npm once. Just navigate to the root of the stac-spec repo and on
your command line run:

```bash
npm install
```
Then to do the check on your markdown you run:

Then to do the check for markdown and examples you run:

```bash
npm run check-markdown
npm run check
```

This will spit out the same text that you see online, and you can then go and fix your markdown.
This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.

To just check the markdown run:

```bash
npm run check-markdown
```

### Working with the OpenAPI files

Expand All @@ -78,6 +79,10 @@ various parts of the specification. Currently we expect developers to be up to s
OpenAPI and using their own tools to modify things. In the future we will provide tools to make it easier to work with.
There are html version of the OpenAPI files online at `https://api.stacspec.org/{version_number}` with `{version_number}` being the git tag or `dev`.

Often, updating
the JSON Schema and OpenAPI files is one of the harder aspects of creating a change, so please, don't
hesitate to ask for help in doing this!

## Release Process

To release a new version of the STAC spec the following list of tasks must be done.
Expand Down Expand Up @@ -125,10 +130,4 @@ with no changes to the spec - just updating the version numbers.

## Governance

The goal of STAC is to have a Project Steering Committee of core contributors, representing diverse organizations and
implementations. To bootstrap Chris Holmes is the Benevolent Dictator for
Life or until a PSC is formed, so we don't get stuck waiting for votes when there is not enough activity.

The longer term goal is to contribute STAC spec to the Open Geospatial Consortium, and indeed to align as much as possible
with their next generation spec. The current plan is to contribute STAC API as an OGC 'community module' when we reach
1.0.0, and to work to have it become part of the OGC API baseline.
The STAC API spec follows the same governance as the [core STAC spec](https://github.com/radiantearth/stac-spec/blob/master/process.md#governance).