Contributing updates (#173)

* update contributing, esp. governance

Author: philvarner

CONTRIBUTING.md

@@ -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
 
@@ -25,50 +26,56 @@ 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-openapi programs 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.
 
 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
+```
+
+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
 ```
 
-This will spit out the same text that you see online, and you can then go and fix your markdown.
+To just validate the OpenAPI definitions, run:
+
+```bash
+npm run check-openapi
+```
 
 ### Working with the OpenAPI files
 
@@ -78,6 +85,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. 
@@ -125,10 +136,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).