radiantearth · cholmes · Nov 19, 2020 · Nov 18, 2020 · Nov 18, 2020 · Nov 18, 2020
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - Updated to STAC specification version 1.0.0-beta.2
+- Named explicit supported STAC core versions to be from 0.9.0 up to (and not including) 2.0.0
 - Context Extension OpenAPI spec was updated to remove the no longer used `next` attribute
 - Added root endpoint Link `search` must have `type` of `application/geo+json`
 - Corrected the description of endpoint `/collections` to say it returns an object per OAFeat, instead of an array of Collection

diff --git a/PROCESS.md b/PROCESS.md
@@ -0,0 +1,72 @@
+## STAC Development & Release Process
+
+### Development Process
+
+The SpatioTemporal Asset Catalog API specification is under active development. 
+
+The `master` branch aims to always be stable, meaning that all the pieces of the specification are consistent and well
+explained, and all the examples are consistent with the specification. The `dev` branch is a place of active development, 
+where a new change in one part of the spec might not yet be fully updated everywhere else. The team uses the 
+[stac-api-spec issue tracker](https://github.com/radiantearth/stac-api-spec/issues) to identify and track all that will be done for 
+a release. Once all the major issues are resolved the core team makes sure everything is consistent across the spec and
+examples.
+
+Any changes to the spec must be made as pull requests to the `dev` branch. Anyone is welcome and encouraged to bring ideas
+and improvements, to the issue tracker or (ideally) as pull requests. To merge a new pull request the work must be reviewed
+by at least two members of the STAC spec core team (who have write access to the main repository). It also must pass the
+Continuous Integration testing.
+
+### Release Process
+
+To release a new version of the STAC spec the following list of tasks must be done. 
+
+- **Update Issue Tracker**: Each release has a [milestone](https://github.com/radiantearth/stac-spec/milestones) in the github 
+issue tracker, and before a release is done all open issues that are filed against it should be reviewed. All issues do not 
+need to be completed, but the core release team should all review the issues to make sure that the critical ones for the 
+release have been addressed. Issues that aren't seen as essential should be moved to future releases, so that there are no
+open issues against the milestone.
+- **Check dependencies**: STAC relies on OGC API - Features and STAC Core specifications at its core, and will likely rely
+on additional Features API extensions as well as OGC API - Commons. We aim to always reference the latest version of these,
+so before releasing we should check to make sure we are on the latest stable versions, and upgrade if it makes sense. We include
+the latest stable STAC core spec version as a 'submodule', so before release we should update that to be the latest.
+- **Agreement from core team**: The core STAC API team should meet (on video or on gitter) and decided that the release is ready.
+This should include review of the issues, as well as looking at the spec holistically, to make sure the new changes keep
+with a coherent whole.
+- **Final Spec Read Through**: There should be a final read through of the core specification to make sure it makes sense
+and there are no typos, errors, etc.
+- **Update the Changelog**: The [changelog](CHANGELOG.md) should be reviewed to make sure it includes all major improvements
+in the release. And anything in 'unreleased' section should move to the version of the spec to be released.
+- **Merge dev to master**: As there is no 'build' process, since the specification *is* the markdown files in the github
+repository, the key step in a release is to merge the `dev` branch into `master`, as `master` is the current stable state 
+of the spec.
+- **Check Online API Docs**: Check to make sure the online API docs reflect the release at <https://stacspec.org/STAC-api.html> 
+and <https://stacspec.org/STAC-ext-api.html> (this step may go away once we are confident this works well, as this publishing is in flux)
+- **Release on Github**: The final step to create the release is to add a new 'release' on 
+<https://github.com/radiantearth/stac-spec/releases>. This should use a tag like the others, with a 'v' prefix and then the 
+release number, like v0.5.2. The changelog should be copied over to be the release notes, and then also include a link to 
+the full milestone of everything closed in the issue tracker.
+- **Promote the release**: A blog post and tweet should be composed and sent out, and then inform those in the gitter channel
+to post / promote it.
+
+#### Release Candidates
+
+Before any release that has *major* changes (made as a judgement call by the core contributors)  there should be a 'release 
+candidate' to ensure the wider community of implementors can try it out
+and catch any errors *before* a full release. It is only through actual implementations that we can be sure the new spec
+version is good, so this step is essential if there are major changes. The release should proceed as normal, but called
+vX.Y.Z-RC.1. The core STAC community should be told and encouraged to update their implementations. At least 2 implementations
+should be updated to the new specification before there is a real release. And ideally an API client is also 
+updated. This provides the core sanity check. If there are changes or fixes to the spec or 
+schemas needed from their feedback then make fixes and do RC2. If it is just fixes to the examples or tooling then no 
+additional RC is needed. After there is no more changes to spec or schemas then the release process should be done on master,
+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.	
diff --git a/README.md b/README.md
@@ -8,16 +8,16 @@ The SpatioTemporal Asset Catalog (STAC) specification aims to standardize the wa
 A 'spatiotemporal asset' is any file that represents information about the earth captured in a certain space and 
 time. The core STAC specification lives at [gitub.com/radiantearth/stac-spec](https://github.com/radiantearth/stac-spec).
 
-A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns a STAC [Catalog](https://github.com/radiantearth/stac-spec/catalog-spec/catalog-spec.md), 
-[Collection](https://github.com/radiantearth/stac-spec/collection-spec/collection-spec.md), [Item](https://github.com/radiantearth/stac-spec/item-spec/item-spec.md), 
+A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns a STAC [Catalog](stac-spec/catalog-spec/catalog-spec.md), 
+[Collection](stac-spec/collection-spec/collection-spec.md), [Item](stac-spec/item-spec/item-spec.md), 
 or ItemCollection, depending on the endpoint.
 Catalogs and Collections are JSON, while Items and ItemCollections are GeoJSON-compliant entities with foreign members.  
 Typically, a Feature is used when returning a single Item, and FeatureCollection when multiple Items (rather than a JSON array of Item entities).
 
 The API is compliant with the *[OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html)* standard 
 (formerly known as *OGC Web Feature Service 3*), in that it defines many of the endpoints that STAC uses. A STAC API should be 
 compatible and usable with any OGC API - Features clients. The STAC API can be thought of as a specialized Features API 
-to search STAC Catalogs, where the features returned are STAC [Items](https://github.com/radiantearth/stac-spec/item-spec/item-spec.md), 
+to search STAC Catalogs, where the features returned are STAC [Items](stac-spec/item-spec/item-spec.md), 
 that have common properties, links to their assets and geometries that represent the footprints of the geospatial assets.
 
 ## Stability Note
@@ -51,6 +51,12 @@ Human-readable versions of the OpenAPI definitions can be viewed online for the
 - [Only the core STAC API](https://stacspec.org/STAC-api.html) 
 - [STAC API including all extensions](https://stacspec.org/STAC-ext-api.html)
 
+**STAC Core Spec:** This repository includes a '[sub-module](https://git-scm.com/book/en/v2/Git-Tools-Submodules)', which
+is a copy of the [STAC Core Spec](stac-spec/) tagged at the latest stable version. This allows
+us to refer to the core spec with relative links. Sub-modules aren't checked out by default, so to get the directory 
+populated either use `git submodule update --init --recursive` if you've already cloned it, or clone from the start with
+`git clone --recursive [email protected]:radiantearth/stac-api-spec.git`. 
+
 ## OpenAPI definitions
 
 The definitive specification for STAC API is provided as an [OpenAPI](http://openapis.org/) 3.0 specification that is

diff --git a/api-spec.md b/api-spec.md
@@ -2,41 +2,53 @@
 
 ## About
 
-The STAC API defines a RESTful JSON-based server to query [SpatioTemporal Asset Catalogs](https://github.com/radiantearth/stac-spec/) 
+The STAC API defines a RESTful JSON-based server to query [SpatioTemporal Asset Catalogs](stac-spec/) 
 (STAC). While the core STAC specification provides a structure and language to describe assets, users usually want to access
 a subset of the entire catalog, such as for a certain date range, in a particular area of interest, or matching properties
 they care about. STAC API specifies those query parameters, and compliant servers return collections of STAC Items that
 match the user's preferences.
 
+## STAC API and STAC Core Spec
+
+The [STAC Core specification](stac-spec) provides most all the content of API responses - the STAC API is primarily concerned
+with the return of STAC [Items](stac-spec/item-spec/README.md) and [Collections](stac-spec/collection-spec/README.md) through
+API's.
+
+This version of STAC API is intended to work with any STAC core specification version 0.9.x or 1.x.x (included betas), but is not 
+designed to work with STAC 2.0 and above (since we use [SemVer](https://semver.org/) it may introduce backwards incompatible changes). 
+The STAC API spec is released with the latest stable STAC core specification version included in the [`/stac-spec`](stac-spec/) 
+directory as a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules). To determine which version it is just check the 
+[`/stac-spec/CHANGELOG.md`](stac-spec/CHANGELOG.md) for the topmost version & release date.
+
 ## STAC API and OGC API - Features
 
-The vast majority of what STAC API does is specified in the *[OGC API - Features](https://ogcapi.ogc.org/features/)*
+The vast majority of the STAC API mechanics are specified in the *[OGC API - Features](https://ogcapi.ogc.org/features/)*
 standard ('OAFeat' for our shorthand). STAC API is fully compliant with [OAFeat - Part 1: Core, version 
 1.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html), and will be aligned with their additional extensions
 when they are finalized. Future STAC API releases will align with [upcoming versions](https://github.com/opengeospatial/ogcapi-features).
 STAC API adds certain requirements and extensions on top of the OAFeat core, to meet its community's use cases, detailed below.
 
 The OGC API - Features is a standard API that represents collections of geospatial data. It defines the RESTful interface 
 to query geospatial data, with GeoJSON as a main return type. With OAFeat you can return any `Feature`, which is a geometry 
-plus any number of properties. The core [STAC Item spec](https://github.com/radiantearth/stac-spec/item-spec/README.md) 
+plus any number of properties. The core [STAC Item spec](stac-spec/item-spec/README.md) 
 enhances the core `Feature` with additional requirements and options to enable cataloging of spatiotemporal 'assets' like 
 satellite imagery. This STAC `Item` always links to an asset, and these assets always have a capture time, so it requires 
 fields for `datetime` and `assets`. 
 
 OAFeat also defines the concept of a Collection, which contains Features. In OAFeat Collections are the sets of data that can 
 be queried ([7.11](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collections_)), and each describes basic 
 information about the geospatial dataset, like its name and description, as well as the spatial and temporal extents of all 
-the data contained. [STAC collections](https://github.com/radiantearth/stac-spec/collection-spec/README.md) contain this same 
+the data contained. [STAC collections](stac-spec/collection-spec/README.md) contain this same 
 information, along with other STAC specific fields to provide additional metadata for searching spatiotemporal assets, and 
 thus are compliant with both OAFeat Collections and STAC Collections and are returned from the `/collections/{collection_id}` 
 endpoint.
 
 In OAFeat Features are the individual records within a Collection and are usually provided in GeoJSON format. 
-[STAC Items](https://github.com/radiantearth/stac-spec/item-spec/README.md) are compliant with the OAFeat Features 
+[STAC Items](stac-spec/item-spec/README.md) are compliant with the OAFeat Features 
 [GeoJSON requirements class](http://docs.ogc.org/is/17-069r3/17-069r3.html#_requirements_class_geojson), and are returned from the 
 `/collections/{collection_id}/items/{item_id}` endpoint. The return of other encodings 
 ([html](http://docs.ogc.org/is/17-069r3/17-069r3.html#rc_html), [gml](http://docs.ogc.org/is/17-069r3/17-069r3.html#rc_gmlsf0))
-is outside the scope of STAC API, as the [STAC Item](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md) is
+is outside the scope of STAC API, as the [STAC Item](stac-spec/item-spec/item-spec.md) is
 specified in GeoJSON.
 
 A typical OAFeat will have multiple collections, and each will just offer simple search for its particular collection at 
@@ -118,7 +130,7 @@ See the [OpenAPI specification document](openapi/STAC.yaml).
 
 | Endpoint  | Returns                                                        | Description |
 | --------  | -------------------------------------------------------------- | ----------- |
-| `/`       | [Catalog](https://github.com/radiantearth/stac-spec/catalog-spec/catalog-spec.md)            | Extends `/` from OAFeat to return a full STAC catalog. |
+| `/`       | [Catalog](stac-spec/catalog-spec/catalog-spec.md)            | Extends `/` from OAFeat to return a full STAC catalog. |
 | `/search` | ItemCollection | Retrieves a group of Items matching the provided search predicates, probably containing search metadata from the `search` extension |
 
 The root endpoint (`/`) is most useful when it presents a complete `Catalog` representation of all the data contained in the API, such that all `Collections` and `Items` can be navigated to by transitively traversing links from this root. This spec does not require any API endpoints from OAFeat or STAC API to be implemented, so these links may not exist if the endpoint has not been implemented.