Added/updated README files and CHANGELOG for SDK 2.

CHANGELOG.md

@@ -1,11 +1,17 @@
-# SDK 2.0.0 Release Notes
+# SDK 2.0.0-alpha.1 - Release Notes
 
-SDK 2.0.0 introduces a new, more expressive version of EFX (the eForms Expression Language) which allows us to improve the visualisation of eForms notices, as well as the expressiveness and readability of business rules.
+SDK 2 introduces a new, more expressive version of EFX (the eForms Expression Language) which allows us to improve the visualisation of eForms notices, as well as the expressiveness and readability of business rules.
 
-Some of the changes introduced with eForms SDK 2, are not backwards compatible with earlier releases. Applications that use SDK 1.x,x, will need to be updated to use the new version of the SDK. 
+## Backwards compatibility
 
-A detailed list of changes as well as a complete migration guide are available in the [eForms SDK 2 "Welcome" document](https://docs.ted.europa.eu/home/eforms/sdk2/).
+:x: **Breaking change**: SDK 2 introduces a new version of the EFX language. As a result, all EFX expressions and templates included in the `fields` and `view-templates` folders have been updated to the new version.
 
-The documentation for the SDK is available at <https://docs.ted.europa.eu/eforms/latest>. The source for this documentation is maintained in the [eforms-docs](https://github.com/OP-TED/eforms-docs) repository.
+:heavy_check_mark: **No other breaking changes** in the metadata provided have been introduced in SDK 2. With the exception of the  updates necessary for EFX parsers, metadata driven applications built on top of SDK 1 should be able to use the metadata provided in SDK 2 without any other changes.
 
-A comprehensive list of changes between SDK 1.7.0 and SDK 2.0.0 can be seen at <https://github.com/OP-TED/eForms-SDK/compare/1.7.0...2.0.0>.
+## Pre-release version
+
+This is a development version of SDK 2. Future pre-release versions might introduce further breaking changes.
+
+A detailed list of changes as well as a complete migration guide are under construction in the [eForms SDK 2 "Welcome" document](https://docs.ted.europa.eu/home/eforms/sdk2/).
+
+A comprehensive list of changes between SDK 1.8.0 and SDK 2.0.0-alpha.1 can be found at <https://github.com/OP-TED/eForms-SDK/compare/1.8.0...2.0.0-alpha.1>.

README.md

@@ -1,31 +1,30 @@
-**[:memo: Latest Release Notes](CHANGELOG.md)** | **[:package: Latest Release Artifacts](https://search.maven.org/search?q=g:%22eu.europa.ted.eforms%22%20AND%20a:%22eforms-sdk%22)**
+# eForms SDK
 
----
+The eForms SDK is a project of the Publications Office of the European Union that aims to facilitate the implementation of the European legislation for the publication of public procurement notices on the [TED website](https://ted.europa.eu). For more information on the legislation, see the [DG GROW eForms page](https://ec.europa.eu/growth/single-market/public-procurement/digital/eforms_en).
 
-# Summary
+## Versioning
 
-This project, managed by the Publications Office of the European Union, aims to facilitate the implementation of the European legislation for the publication of public procurement notices on the [TED website](https://ted.europa.eu). For more information on the legislation, see the [DG GROW eForms page](https://ec.europa.eu/growth/single-market/public-procurement/digital/eforms_en). 
+The eForms SDK uses semantic versioning. For more information, see the [versioning guide](https://docs.ted.europa.eu/eforms/latest/versioning).
 
-The eforms SDK provides the necessary resources for building eForms applications that create, edit, visualise, validate and submit for publication, valid eForms notices.
-It contains several different metadata assets, organised in folders as follows:
-- `codelists`: The controlled vocabularies (codelists) used in eForms notices, as [Genericode files](https://docs.oasis-open.org/codelist/genericode/doc/oasis-code-list-representation-genericode.html).
-- `schemas`: The XML schemas used for eForms notices. The schemas are based on Pre-Award document types of the [UBL 2.3 standard](https://docs.oasis-open.org/ubl/UBL-2.3.html).
-The adopted approach is to keep the whole set of UBL elements but only support the use of a subset. It provides the advantage of having the rules outside of the schema. Adding extra fields for which a UBL element already exists will not require the definition of a new schema.
-- `efx-grammar`: The ANTLR4 grammar for the eForms expression language (EFX).
-- `schematrons`: The Schematron rules used to check the validity of notices as per the eForms regulation. All rules and constraints are implemented in Schematron.
-- `examples`: Examples of eForms notices together with their validation report in SVRL.
-- `notice-types`: Notice type definitions, in JSON format, for each notice subtype. They provide the necessary information for creating a form for filling-in a notice.
-- `fields`: Information on the fields that compose an eForms notice.
-- `view-templates`: Structured information on the visualisation of notices.
-- `translations`: Translations of various labels and short texts used in eForms notices.
+## Latest Stable Release
 
-You can download the latest release from Maven Central.  
-[![Maven Central](https://img.shields.io/maven-central/v/eu.europa.ted.eforms/eforms-sdk.svg?label=Download)](https://search.maven.org/search?q=g:%22eu.europa.ted.eforms%22%20AND%20a:%22eforms-sdk%22)
+The latest stable version of the eForms SDK is released under major version 1. At the time this document file was last updated, the latest stable release was SDK 1.7.0. You can download the latest SDK 1.x.x from [Maven Central](https://central.sonatype.com/artifact/eu.europa.ted.eforms/eforms-sdk). 
 
-The documentation is available at https://docs.ted.europa.eu/eforms/latest.
+## Pre-Release Version
 
-# Versioning
+We are currently developing the next major version of the eForms SDK. This pre-release version, version 2.0.0-alpha.1, is still a work in progress and should not be used in production environments.
 
-The eForms SDK uses semantic versioning. For more information: https://docs.ted.europa.eu/eforms/latest/versioning
+### What's New in the Pre-Release Version
 
-Provisional releases of the eForms schema and documentation that were provided during 2020 via SIMAP had a different versioning scheme and are replaced with this SDK that combines them into one bundle with one version number.
+The alpha release of the eForms SDK includes several updates in the EFX grammar. For a full list of changes, see the [CHANGELOG.md](CHANGELOG.md).
+
+### Testing and Feedback
+
+We encourage users to test the pre-release version of the eForms SDK and provide feedback to help us improve the final release. 
+## Documentation
+
+The documentation for the eForms SDK is available at https://docs.ted.europa.eu/eforms/latest.
+
+## License
+
+The eForms SDK is released under the Creative Commons Attribution 4.0 International license. For more information, see the [LICENSE](LICENSE) file.

codelists/README.md

@@ -0,0 +1,10 @@
+# The `codelists` folder
+
+This folder provides the controlled vocabularies used in eForms notices. The format used is the [Genericode](https://docs.oasis-open.org/codelist/genericode/doc/oasis-code-list-representation-genericode.html) file format. 
+
+The `codelists.json` file serves as an index listing all the codelists available in this folder together with some essential metadata about each of them (like its identifier, filename, description etc.).
+
+Documentation on how to use the metadata provided in this folder can be found at <https://docs.ted.europa.eu/eforms/latest/codelists>.
+
+## SDK 2: Backwards compatibility
+:heavy_check_mark: **No breaking changes** in the metadata provided in this folder have been introduced by SDK 2. Metadata driven applications built on top of SDK 1 should be able to use the metadata provided in this folder without any changes.

efx-grammar/README.md

@@ -0,0 +1,13 @@
+# The `efx-grammar` folder
+
+This folder contains the grammar of the eForms Expression Language (EFX). 
+
+EFX is a domain specific language (DSL) designed to be used for formally encoding validation rules, as well as visualisation templates for eForms notices. The grammar is designed to be used with the [ANTLR4](https://www.antlr.org/) parser generator.
+
+Documentation of the eForms Expression Language can be found at https://docs.ted.europa.eu/eforms/latest/efx.
+
+## SDK 2: Backwards compatibility
+
+:x: **Breaking change**: SDK 2 introduces a new version of the EFX language. As a result, applications that parse EFX will need to be updated to support the new version of the grammar.
+
+The EFX 2 grammar is mostly backwards compatible with the previous version. For details on the changes introduced in SDK 2, see [what's new in EFX 2 ](https://docs.ted.europa.eu/home/eforms/sdk2/efx2.html).

examples/README.md

@@ -1,22 +1,22 @@
-# Examples
+# The `examples` folder
 
 The files available in this folder are published to provide examples to anyone implementing the eForms regulation.
 
 ## Notices
 
-The folder "notices" contains examples of eForms XML notices.
+The `notices` subfolder contains examples of eForms XML notices.
 
-The notices with a filename starting with "INVALID_" are intentionally invalid, and are used to assess the completeness of the validation rules.
+The notices with a filename starting with `INVALID_` are intentionally invalid, and are used to assess the completeness of the validation rules.
 
 Some of the notices are based on a notice published on TED, and in that case the link to that notice is indicated in a comment at the start of the file.
 
-The notices "cn_24_FRA_comments.xml" and "can_24_FRA_comments.xml" are of specific interest, as they are quite exhaustive, and contain comments referring to the corresponding Business Terms.
+The notices `cn_24_FRA_comments.xml` and `can_24_FRA_comments.xml` are of specific interest, as they are quite exhaustive, and contain comments referring to the corresponding Business Terms.
 
 
 ## Validation reports
 
-The folder "reports" contains the results of the validation of the notice examples with the Schematron rules provided in this repository.
+The `reports` subfolder contains the results of the validation of the notice examples with the Schematron rules provided in this repository.
 
 The validation reports are in SVRL (Schematron Validation Report Language). 
 
-Each report has the same filename as the corresponding notice, with the extension ".svrl".
+Each report has the same filename as the corresponding notice, with the extension `.svrl`.

fields/README.md

@@ -0,0 +1,13 @@
+# The `fields` folder
+
+This folder contains the field metadata for eForms notices. 
+
+The metadata provided in `fields.json` constitutes the conceptual model of eForms, which is intended to abstract the information contained in the eForms schemas, and provide a layer on top of which forms, visualisations, and business logic can be built. The metadata is provided in JSON format.
+
+Documentation of the metadata provided in this folder can be found at https://docs.ted.europa.eu/eforms/latest/fields.
+
+## SDK 2: Backwards compatibility
+
+:x: **Breaking change**: SDK 2 introduces a new version of the EFX language. As a result, all **EFX expressions** included in `fields.json` have been updated to the new version.
+
+:heavy_check_mark: **No other breaking changes** in the metadata provided in this folder have been introduced by SDK 2. Metadata driven applications built on top of SDK 1 should be able to use the metadata provided in this folder without any changes. 

notice-types/README.md

@@ -0,0 +1,8 @@
+# The `notice-types` folder
+
+This folder contains "notice type definitions", in JSON format. The files, which  are organized by notice subtype, provide the necessary information for creating a form for filling-in a notice.
+
+Documentation of the metadata provided in this folder can be found at https://docs.ted.europa.eu/eforms/latest/notice-types.
+
+## SDK 2: Backwards compatibility
+:heavy_check_mark: **No breaking changes** in the metadata provided in this folder have been introduced by SDK 2. Metadata driven applications built on top of SDK 1 should be able to use the metadata provided in this folder without any changes.

schemas/README.md

@@ -0,0 +1,10 @@
+# `schemas` folder
+
+This folder contains  the XML schemas used for eForms notices. The schemas are based on pre-award document types of the [UBL 2.3 standard](https://docs.oasis-open.org/ubl/UBL-2.3.html).
+
+The adopted approach is to keep the whole set of UBL elements but only support the use of a subset. It provides the advantage of having the rules outside of the schema. Adding extra fields for which a UBL element already exists will not require the definition of a new schema.
+
+Documentation of the eForms Schemas can be found at https://docs.ted.europa.eu/eforms/latest/schema.
+
+## SDK 2: Backwards compatibility
+:heavy_check_mark: **No breaking changes** in the metadata provided in this folder have been introduced by SDK 2. Metadata driven applications built on top of SDK 1 should be able to use the metadata provided in this folder without any changes.

schematrons/README.md

@@ -1,4 +1,4 @@
-# eForms Schematron rules
+# The `schematrons` folder
 
 The Schematron rules used to validate eForms notices.
 
@@ -29,3 +29,7 @@ The URL of this service is configured by a variable defined in the file `config.
 The schematron rules can be executed via any standard Schematron implementation, using the file `complete-validation.sch`.
 
 If you use the XSLT implementation at https://github.com/Schematron/schematron, you must implement the following fix so that rules on attributes are fired: https://github.com/Schematron/schematron/issues/29.
+
+## SDK 2: Backwards compatibility
+
+:heavy_check_mark: **No breaking changes** in the metadata provided in this folder have been introduced by SDK 2. Metadata driven applications built on top of SDK 1 should be able to use the metadata provided in this folder without any changes.

translations/README.md

@@ -0,0 +1,8 @@
+# The `translations` folder
+
+This folder provides natural language texts (names, descriptions, tooltips etc.) associated with any business term or other entity that is defined in the eForms Regulation and contained within the eForms SDK.
+
+Documentation on how to use the metadata provided in this folder can be found at <https://docs.ted.europa.eu/eforms/latest/translations>.
+
+## SDK 2: Backwards compatibility
+:heavy_check_mark: **No breaking changes** in the metadata provided in this folder have been introduced by SDK 2. Metadata driven applications built on top of SDK 1 should be able to use the metadata provided in this folder without any changes.

view-templates/README.md

@@ -0,0 +1,13 @@
+# The `view-templates` folder
+
+This folder contains EFX view templates for eForms notice visualisation.
+
+The `view-templates.json` file serves as an index, listing all the view templates available in this folder together with some essential metadata about each of them (like its identifier, filename, description etc.).
+
+Documentation of the eForms Expression Language and EFX template syntax can be found at https://docs.ted.europa.eu/eforms/latest/efx.
+
+## SDK 2: Backwards compatibility
+
+:x: **Breaking change**: SDK 2 introduces a new version of the EFX language. As a result, the notice visualisation templates provided in this folder use the new EFX syntax. If your application parses this files you will need to update your EFX parsers to support the new version of the grammar. 
+
+The EFX 2 grammar is mostly backward compatible with EFX 1. For details on the changes introduced in SDK 2, see [what's new in EFX 2 ](https://docs.ted.europa.eu/home/eforms/sdk2/efx2.html).