@author: Alessia Bardi
@date: 28/9/2018
@description: read me file to update schemas and schema documentation for OpenAIRE

This folder contains the files that are publicly available.
There is one folder per schema version, plus one folder for sygma schema.
Each schema folder contains:
- doc: folder with html documentation. The documentation must be automatically generated via Oxygen. Please find instructions below.
- a set of xsd files

The latest schema version must be available in 'latest', which is a symbolic link.
Currently for example: 
lrwxr-xr-x   1 alessia  staff    3 Sep 28 10:47 latest -> 1.0

A schema that has already been published must never be updated. A new version must instead be released, i.e. you must create a new folder under 'schema' whose name is the new version.

Current published version is 1.0.

Next schema version should be:
- 1.2 if there are no major, breaking changes (i.e. only additions or vocabulary changes)
- 2.0 if there are major breaking changes (i.e. deletion of fields, breaking type changes)

---- DEPLOYMENT INFO ----
Never ever change the files directly in the folder of the OpenAIRE server! Changes there CANNOT be committed. 
Work on your local machine, follow the instructions https://svn.driver.research-infrastructures.eu/driver/dnet45/modules/dnet-openaire-schema/trunk and then type the following on the OpenAIRE server:

> sudo su - www-data -s /bin/bash
> cd /var/www/schema
> svn up

Current deployment info:
- machine: new.openaire.eu
- location: /var/www/schema
- user: www-data

---- HOW TO GENERATE THE DOC FOLDER WITH OXYGEN ---
Let's suppose we want to publish version X.Y. This means that we have a folder `schema/X.Y`. 
1. Commit `schema/X.Y` on svn.
2. Go to the OpenAIRE server via ssh (new.openaire.eu) and update the schema folder:
    > sudo su - www-data -s /bin/bash
    > cd /var/www/schema
    > svn up
    Now you should see folder `/var/www/schema/X.Y` and https://www.openaire.eu/schema/X.Y/oaf-X.Y.xsd should be accessible. Check it.
3. Now we can generate the documentation via Oxygen.
3.1 Open Oxygen in your local machine and select: Tools --> Generate Documentation --> XML Schema Documentation 
3.2 Click on Import Settings and select the file `schema/docGenerationSettings.xml`. Settings are:
    - output format: splitted by location
    - all settings option checked
    - images in jpeg
3.3 Set the schema URL to https://www.openaire.eu/schema/X.Y/oaf-X.Y.xsd (if we select the file on the local file system, then the documentation will contain references to the local file system, while we want documentation to refer to www.openaire.eu)
3.4 Modify the output file by changing X.Y to the actual version you are working with
3.5 Click on `Generate`.
3.6 Check the documentation is currently stored under `schema/X.Y/doc` and images under `schema/X.Y/doc/img`
3.7 Create a symlink for `doc/oaf-X.Y.html` with a name with no version (needed to have a clean URL for the entry point to the latest documentation)
    > cd schema/X.Y/doc
    > ln -s oaf-X.Y.html oaf.html
4. Commit the `schema/X.Y/doc` folder
5. Go to the OpenAIRE server via ssh (new.openaire.eu) and update the schema folder:
    > sudo su - www-data -s /bin/bash
    > cd /var/www/schema
    > svn up
    Now https://www.openaire.eu/schema/X.Y/oaf-X.Y.html should be accessible. Check it.
6. Update the `latest` folder   
6.1 Update the `latest` on your local copy of https://svn.driver.research-infrastructures.eu/driver/dnet45/modules/dnet-openaire-schema/trunk
    > cd schema/latest
    > rm -rf *
    > ln -s ../X.Y/oaf-X.Y.xsd oaf.xsd
    > ln -s ../X.Y/oaf-common-X.Y.xsd oaf-common-X.Y.xsd
    > ln -s ../X.Y/oaf-datasource-X.Y.xsd oaf-datasource-X.Y.xsd
    > ln -s ../X.Y/oaf-org-X.Y.xsd  oaf-org-X.Y.xsd
    > ln -s ../X.Y/oaf-person-X.Y.xsd oaf-person-X.Y.xsd
    > ln -s ../X.Y/oaf-project-X.Y.xsd oaf-project-X.Y.xsd
    > ln -s ../X.Y/oaf-result-X.Y.xsd  oaf-result-X.Y.xsd
    > ln -s ../1.0/doc doc 
    > svn commit latest -m "updated latest links to version X.Y"
6.2 Update again on the OpenAIRE server folder
    > sudo su - www-data -s /bin/bash
    > cd /var/www/schema
    > svn up
6.3 Check the latest links refer to the new schema:
    * https://www.openaire.eu/schema/latest/oaf.xsd
    * https://www.openaire.eu/schema/latest/doc/oaf.html
7. Update the API documentation following instructions on https://svn.driver.research-infrastructures.eu/driver/dnet45/modules/dnet-api-http-doc/