RELEASING.TXT

0-a) Technical pre-conditions for release.

Overview

Code, schema, examples and supporting documentation should be in a stable state.

Pay particular attention to release-specific structures and docs/releases.html
(e.g. no stray '2.x', '2.*' etc. in hidden markup or tables)

In sdoapp.py we declare the current version. This should match the number
chosen in /docs/releases.html (check markup assigns an HTML ID too).

The following steps assume a general healthy freeze (tested / QA as below).

in versions.json:

    "schemaversion": "3.9",
    "releaseLog": {  
.
.
        "3.8": "2019-07-01",
        "3.9": "2019-08-01" 
    }
becomes
    "schemaversion": "4.0",
    "releaseLog": {  
.
.
        "3.8": "2019-07-01",
        "3.9": "2019-08-01", 
        "4.0": "2019-10-01" 
    }

... this should have a release date for the current release and all
previous releases that are archived under data/releases/{version}/*


e.g.
    data/releases/2.1
    data/releases/2.1/all-layers.nq
    data/releases/2.1/core.nq
    data/releases/2.1/ext-auto.nq
    data/releases/2.1/ext-bib.nq
    data/releases/2.1/README.md
    data/releases/2.1/schema-all.html
    data/releases/2.1/schema.nt
    data/releases/2.1/schema.rdfa

All these are all created and coppied where appropriate by running the 'scripts/buildreleasefiles.sh' script
[since version 3.9]


Example usage:
    scripts/buildreleasefiles.sh 3.9



1) General preconditions / process and QA for release.

1-a) Steering Group have signed off on changes and release plan,
and no active and unresolved disputes in the Community Group.

1-b) All code is commited to appropriate release branch at Github (usually
configured as the current default github branch for /schemaorg/ project).

1-c) All tests pass.
It is best to test against a fresh checkout to avoid depending on uncommitted
files. The unit tests depend upon a local installation of Google AppEngine, e.g.

PYTHONPATH=/usr/local/google_appengine ./scripts/run_tests.py

To run the full unit tests (graph test of schema integrity) the 'rdflib'
python library is also needed: 'sudo easy_install rdflib' should do it.

 Example transcript:

  git clone https://github.com/schemaorg/schemaorg.git
  Cloning into 'schemaorg'...
  remote: Counting objects: 6375, done.
  remote: Compressing objects: 100% (80/80), done.
  remote: Total 6375 (delta 43), reused 0 (delta 0), pack-reused 6295
  Receiving objects: 100% (6375/6375), 27.62 MiB | 1.01 MiB/s, done.
  Resolving deltas: 100% (4074/4074), done.
  Checking connectivity... done.
  danbri-macbookpro2:tmp danbri$ cd schemaorg/

  [...]

  Ran 70 tests in 21.168s

  OK (expected failures=3)

1-d) Latest candidate release branch is pushed to per-branch appspot instance
(e.g. sdo-phobos.appspot.com) and the generic unstable upstream site
(i.e. webschemas.org).

1-e) The manual QA page /docs/qa.html has been reviewed to ensure
representative pages of each type appear to be in a healthy state.

e.g. see http://webschemas.org/docs/qa.html

2.) Final checks

There is often some final tweaking, bugs, etc. When things settle down, a
final round of sanity-check tests is useful:

* Run again './scripts/buildreleasefiles.py' 


Using gcloud deployment script
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use python deploment script:

        ./scripts/deployschema.org.sh - to deploy to main Schema.org site
        ./scripts/deploywebschemas.org.sh - to deploy to main webschemas.org site
        
        * Choose Local option to deploy local configuration files
        * Choose Remote option to pull files from a URL (eg. the github repository)
        
        * Provide an appropriate version string - different to currently running version
        * Optionally pass -e to bypass site exercise option
        * Optionally pass -m to bypass merge of new version
        
	
Recommended Method For Making Release Live
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For Webschema.org
    Use ./scripts/deploywebschemas.org.sh -e
        No real benefit in exercising low traffic site 
        
For Schema.org.

    Either run ./scripts/deployschema.org.sh 
        This will put the new site live when site exercise is complete (takes some time)
    or run ./scripts/deployschema.org.sh -m
        At some time after site exercise is complete login to console and manually migrate traffic


5.) Tag the code at the current relese state
* Use a local copy of the relesed version of the 'master' branch:
    * Either download a new clone, or do a 'git pull' on a local copy and then 'git checkout -b master'
* Confirm previous tags: 'git tag -l'
* Tag the local copy eg: 'git tag v3.8-release'
* Push tagged version to github: 'git push origin v3.8-release'
Note: If master has moved on from the the released version before tagging
    * Obtain the last commit identifier before the release from the listing: 'git log master'
    * Add the commit id to the tag comand. eg: 'git tag v3.8-release 7f86a944e1bd87008cb7b83dc7e19a562ed2d28d'

6.) Related post-release tasks.

* Let the Community Group and Steering Group know.
* Blog post.
* There's a SPARQL database at DYDRA that can load NQuad dumps from
https://github.com/schemaorg/schemaorg/blob/sdo-phobos/data/releases/2.2/all-layers.nq
* Make a new per-release branch, reserve an appspot.com account for it.
* Configure GitHub with the new default branch.
  See https://github.com/schemaorg/schemaorg/settings/branches
* Update issue tracker moving issues to new releases.
 * Close issues that were addressed in this release.
 * Make careful considered adjustment to expected release for the rest. Or
   just tag them all for the next release.
* Update git release tags (TODO: we have no history of handling this yet).

For example, if we are in 'master' and 'git status' shows it in a clean state,

* git checkout -b sdo-deimos
* This tells us we can do:
 *     git push --set-upstream origin sdo-deimos

> To https://github.com/schemaorg/schemaorg.git
>  * [new branch]      sdo-deimos -> sdo-deimos
> Branch sdo-deimos set up to track remote branch sdo-deimos from origin.

TODO:

 * clean up release tags
 * see also: git log --pretty=fuller --since="2018-06-15"