From 34673179c6867d09f836c7cd1834878ed671b206 Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Thu, 17 Dec 2015 14:13:10 +0100 Subject: [PATCH 01/14] Initial draft --- README.md | 41 +++++++++++++++++++++++ api-design.md | 82 +++++++++++++++++++++++++++++++++++++++++++++ change-proposals.md | 62 ++++++++++++++++++++++++++++++++++ partners.md | 12 +++++++ repos.md | 54 +++++++++++++++++++++++++++++ statuses.md | 53 +++++++++++++++++++++++++++++ 6 files changed, 304 insertions(+) create mode 100644 README.md create mode 100644 api-design.md create mode 100644 change-proposals.md create mode 100644 partners.md create mode 100644 repos.md create mode 100644 statuses.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4fb9c96 --- /dev/null +++ b/README.md @@ -0,0 +1,41 @@ +Erasmus Without Paper (EWP) - Technical Documentation +===================================================== + +[What is the status of this document?](statuses.md) + + +Preamble +-------- + +This page (as well as most of the other repositories hosted on GitHub) is **for +developers**. You'll need to have experience with Git to be able to work with +GitHub properly. + + * If you are not a developer, please assign a developer from your team to + keep track of all changes to EWP pages (just click the "Watch" button in + the header of the subprojects you want to watch). + + * These developers MUST be able to propose new changes to the API and accept + API change proposals from other developer in the name of the partner (we + will provide each other ample time for reading all the proposed changes). + +**Erasmus Without Paper (EWP)** project aims to ease exchanging data on student +mobility between computer systems in different countries. In order to join EWP, +you will need to implement a subset of its APIs. We require all partners to +follow some basic rules described in the documents below. + + +Important documents +------------------- + +These documents are our proposals on **how** to work with the technical +documentation within the EWP project (where to store it, how to submit change +proposals, etc.). These documents are currently DRAFTs only, and need to be +reviewed and accepted by all the partners before we start defining APIs. + + * [The Structure of EWP Repositories](repos.md) + * [Rules for API Design, Usage and Versioning](api-design.md) + * [Determining the statuses of documents](statuses.md) + * [Rules for Submitting API Change Proposals](change-proposals.md) + * [The list of developer representatives of EWP partners](partners.md) + * [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) diff --git a/api-design.md b/api-design.md new file mode 100644 index 0000000..48b1243 --- /dev/null +++ b/api-design.md @@ -0,0 +1,82 @@ +Rules for API Design, Usage and Versioning +========================================== + +[What is the status of this document?](statuses.md) + + +Semantic Versioning +------------------- + +We use **Semantic Versioning** in all our API documentation. It has enormous +advantages, when it comes to working (and reworking) API design: + + * It allows us to tag specific API versions as officially approved. + + * It allows the developers to easily determine when a breaking change occurs + in a particular API, and adapt properly. + + * It follows [a set of quite explicit rules](http://semver.org/). Please get + familiar with them (especially if you plan to design parts of the APIs). + + * Combined with requirement of preparing a explicit and strict API + specifications, it allows us to easily answer the question: **if it doesn't + work then who's fault is that?** + + +Permalinks +---------- + +Whenever you post a new release of an API somewhere, you SHOULD use a Git tag +name (or a commit ID) in the posted URL. You should avoid posting links to the +`master` branch (which can mutate, even to the point of having the link +broken). + +Try pressing y key on GitHub site to get a permalink ([other useful +keyboard shortcuts](https://help.github.com/articles/using-keyboard-shortcuts/)). + + +Backward-compatibility +---------------------- + +As required by the rules of [semantic versioning](http://semver.org/), all +[breaking changes](https://en.wiktionary.org/wiki/breaking_change) (aka +backward-incompatible changes) SHOULD force the MAJOR API version number to be +increased. + +Once a document is [released](statuses.md), such backward-incompatible +changes SHOULD be avoided (is possible). + +All non-trivial changes (especially the backward-incompatible ones!) must go +through the proposal acceptance process, as described in the +[Rules for Submitting API Change Proposals](change-proposals.md) document. + + +Changelogs (aka Release Notes) +------------------------------- + +Once an API is [released](statuses.md), every subsequent release of this API +MUST be accompanied by a *changelog*. All changes SHOULD be noted in this +changelog (and *backward-incompatible* changes should be additionally +highlighted). + +Please note, that this requirement is for **released** documents only, and it +does not imply the need of having a changelog for [change proposals] +(statuses.md). Before accepting a proposal, a partner SHOULD review the full +diff of the proposed change. + + +XML Schemas or REST? +-------------------- + +It is okay for one API to use JSON and be documented in Markdown, while some +other API uses XML and is documented in XML Schema. We do not put any +restrictions on the format of the API specifications, but we do have some other +requirements: + + * We require all the API specifications to be **explicit and strict**. If any + part of the specifications turns out to be vague, then a new version of such + specification SHOULD be released, fixing the vague part. + + * Try to avoid changing the format of the specification after it has been + accepted, as this will "break the diffs". + diff --git a/change-proposals.md b/change-proposals.md new file mode 100644 index 0000000..5c96c3e --- /dev/null +++ b/change-proposals.md @@ -0,0 +1,62 @@ +Rules for Submitting API Change Proposals +========================================= + +[What is the status of this document?](statuses.md) + + +How to propose a change to an [draft](statuses.md) API? +---------------------------------------------------------------- + +Every API repository has an integrated issue tracker: + + * The author of the API (and all other watchers) will be notified when you a + submit a new issue to the tracker. + + * If you want, you can also fork the repository and attach a pull request to + your issue. Since it's a draft, the author may merge such pull requests at + will (he doesn't need to consult any of the partners yet). + + +How to propose a change to [released](statuses.md) API? +---------------------------------------------------------------- + + * If you're not the API author, just do the same, as with the draft APIs + (described above). + + * If you are the API author yourself, you can push your proposed changes to a + separate branch (or fork), then issue yourself a pull request. + + * Only trivial changes of accepted APIs may be merged without asking for the + approval of the other partners. All non-trivial proposals SHOULD be accepted + before merging them. + + +How to get my [draft](statuses.md) or [change proposal](statuses.md) +[released](statuses.md)? +-------------------------------------------------------------------- + +You CANNOT assume that all partners are watching repository's issues. You +MUST contact all the partners **directly** before you can deem your proposal as +ready to be released. + + * [Breaking changes](https://en.wiktionary.org/wiki/breaking_change) to + existing [releases](statuses.md) MUST be explicitly accepted by all + the partners. + + * Non-breaking changes to existing releases MAY be deemed as implicitly + accepted no sooner than **1 week** after they have been proposed (and no + "veto" was received), but this time span SHOULD be extended if there is + reason to suspect some partners may don't like it. + + * Upgrading [draft](statuses.md) to a [release candidate](statuses.md) MUST be + explicitly accepted by all the partners. + + * All [change proposals](statuses.md) MUST be accompanied by a pull request. + Partners MUST be able to review a diff of all changes, and comment on this + diff. + + +How to contact the partners "directly"? +--------------------------------------- + +*To be decided.* diff --git a/partners.md b/partners.md new file mode 100644 index 0000000..f5ec37b --- /dev/null +++ b/partners.md @@ -0,0 +1,12 @@ +The list of developer representatives of EWP partners +===================================================== + +This is the list of developers who are allowed to accept the API change +proposals in the name of a partner: + +* **Poland**: + + * Wojciech Rygielski - rygielski@mimuw.edu.pl + * Michał Kurzydłowski - michalk@mimuw.edu.pl + +* *(full list of partners - TODO)* diff --git a/repos.md b/repos.md new file mode 100644 index 0000000..6d86b11 --- /dev/null +++ b/repos.md @@ -0,0 +1,54 @@ +The Structure of EWP Repositories +================================= + +[What is the status of this document?](statuses.md) + + +Why GitHub? +----------- + +We chose to use GitHub as the primary tool for working and hosting API +documentation for developers: + + * All developers are familiar with Git. Many developers are also familiar with + GitHub. + + * GitHub allows us to easily keep track of all the changes. Having the option + to diff the changes in the documentation (e.g. "what has changed between + versions 1.0.0 and 1.2.7?") is a very important feature. + + * GitHub features include an integrated code review tools, issue tracker, + change notifications, automated build tools... and many others, all useful + in such projects (even in documentation-only projects!). + + +Why separate API repositories? +------------------------------ + +We chose to split EWP requirements into a couple of separate APIs, and host +them in separate GitHub repositories: + + * We believe that all partners should have the option to implement just + a **subset** of all the features we have documented. This will make it + easier for them to start off, claim that they have parts of EWP properly + implemented, and then implement other parts later (possibly much later, with + other teams of developers). + + * Having each API in **separate repository** has some great advantages, when + it comes to versioning: + + - If a partner does not implement *API X*, then he also knows that he may + ignore all the changes in *API X*'s repository. + + - If a partner have already implemented *API Y* and wants to upgrade his + implementation to include some new changes in new API release, he may + simply review a diff (and/or release notes) in the Git repository between + specific tags. + + - It allows us to use [semantic versioning](http://semver.org/) separately + on each API. This allows the partners to easily spot backward-incompatible + changes which may break their implementations. + + * It allows the project leaders to choose separate teams for working with + separate APIs. Each team will have its own issue tracker and will be in + charge of assigning Git push permissions. diff --git a/statuses.md b/statuses.md new file mode 100644 index 0000000..a958d4c --- /dev/null +++ b/statuses.md @@ -0,0 +1,53 @@ +Document statuses +================= + +[What is the status of this document?](statuses.md) + + +Available statuses +------------------ + +* **DRAFT** - A designer (or a small group of designers) are still working on + this document. It has not been approved (nor anyone was asked to approve it), + but - since it's online - everyone may comment on it. + +* **CHANGE PROPOSAL** - A document is a copy of other document with a set of + changes applied. The partners are asked to comment on the *changed* parts of + the document. + +* **RELEASE CANDIDATE** - All partners have approved the contents of the + document, but it has not been officially released yet (it has no version + number assigned). + +* **RELEASED** - All partners have approved the document and it has been + assigned a version number (e.g. 1.0.0). + +* **OUTDATED** - The document has been made obsolete by a newer release (and + the newer release MAY be backward-incompatible with this document). + + +How to determine the status of a document? +------------------------------------------ + +The status of a document is determined from its **location and context**: + + * If a document has been tagged with a Git version tag (such as `v1.0.0`) + in one of the official repositories, and there is no newer release of this + document (no version with a greater tag name) then its status is + **RELEASED**. + + * If a document has been tagged with a Git version tag, but there exists a + newer tag of this document, then its status is **OBSOLETE**. + + * If a document has been merged into the `stable` branch of one of the + official repositories - then the status of this documented is **RELEASE + CANDIDATE**. + + * If a document has not been merged into the `stable` branch yet, but there + already exists an appropriate open pull request for its merging - then the + status of this documented is **CHANGE PROPOSAL**. + + * In all other cases - the document is a **DRAFT**. + +Official repositories are the ones owned by the **erasmus-without-paper** +GitHub organization. From 58fc27937f8345feed4d741be4a778dce2186b0e Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Mon, 21 Dec 2015 12:18:07 +0100 Subject: [PATCH 02/14] Multiple changes: - We want a single issue tracker for all the projects. - Added a section for preferred data and documentation formats. - Made documentation clearer in multiple places. --- README.md | 31 +++++++++++++++++++++++++------ api-design.md | 39 +++++++++++++++++++++++++++------------ change-proposals.md | 39 ++++++++++++++++++++++++--------------- repos.md | 12 ++++++------ statuses.md | 4 ++-- 5 files changed, 84 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 4fb9c96..9787a06 100644 --- a/README.md +++ b/README.md @@ -7,16 +7,15 @@ Erasmus Without Paper (EWP) - Technical Documentation Preamble -------- -This page (as well as most of the other repositories hosted on GitHub) is **for -developers**. You'll need to have experience with Git to be able to work with -GitHub properly. +This page is written by developers and **for developers**. You'll need to have +experience with Git to be able to work with GitHub properly. * If you are not a developer, please assign a developer from your team to keep track of all changes to EWP pages (just click the "Watch" button in the header of the subprojects you want to watch). * These developers MUST be able to propose new changes to the API and accept - API change proposals from other developer in the name of the partner (we + API change proposals from other developers in the name of the partner (we will provide each other ample time for reading all the proposed changes). **Erasmus Without Paper (EWP)** project aims to ease exchanging data on student @@ -25,8 +24,8 @@ you will need to implement a subset of its APIs. We require all partners to follow some basic rules described in the documents below. -Important documents -------------------- +Rules for working with technical docs within EWP +------------------------------------------------ These documents are our proposals on **how** to work with the technical documentation within the EWP project (where to store it, how to submit change @@ -39,3 +38,23 @@ reviewed and accepted by all the partners before we start defining APIs. * [Rules for Submitting API Change Proposals](change-proposals.md) * [The list of developer representatives of EWP partners](partners.md) * [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) + + +Issue tracker? +-------------- + +*The location of the issue tracker is yet to be agreed upon.* + +GitHub offers built-in issue tracking which would be entirely sufficient for +purposes of developing the software and its documentation. However: + + * There are also other (external) issue trackers which would also suffice for + this particular purpose. + + * If GitHub turns out to be NOT sufficient for other parts of the EWP project + (and developers are not the only ones who need issue tracking) - then we + SHOULD try to find a common solution which would play out well for everyone. + + * We SHOULD have only one issue tracker. Having multiple issue trackers might + lead to confusion. E.g. a term "issue #123" might become ambiguous. + diff --git a/api-design.md b/api-design.md index 48b1243..545fdc3 100644 --- a/api-design.md +++ b/api-design.md @@ -18,7 +18,7 @@ advantages, when it comes to working (and reworking) API design: * It follows [a set of quite explicit rules](http://semver.org/). Please get familiar with them (especially if you plan to design parts of the APIs). - * Combined with requirement of preparing a explicit and strict API + * Combined with the requirement of preparing a explicit and strict API specifications, it allows us to easily answer the question: **if it doesn't work then who's fault is that?** @@ -65,18 +65,33 @@ does not imply the need of having a changelog for [change proposals] diff of the proposed change. -XML Schemas or REST? --------------------- +Preferred Data Format +--------------------- -It is okay for one API to use JSON and be documented in Markdown, while some -other API uses XML and is documented in XML Schema. We do not put any -restrictions on the format of the API specifications, but we do have some other -requirements: +*The preferred data format is yet to be decided upon.* - * We require all the API specifications to be **explicit and strict**. If any - part of the specifications turns out to be vague, then a new version of such - specification SHOULD be released, fixing the vague part. + * XML? + * JSON? - * Try to avoid changing the format of the specification after it has been - accepted, as this will "break the diffs". +Preferred Documentation Format +------------------------------ + +*The preferred documentation format is yet to be decided upon.* + + * Markdown? + * reStructuredText? + * JSON Schema? + * XML Schema? + +However, regardless of what we choose, we do have some requirements on the +documentation itself: + + * We require all API specifications to be **explicit and strict** (with lots + of "MUSTs" and "MUST NOTs" and detailed explanations for all the + enumerations used). If any part of the specifications turns out to be vague, + then a new version of such specification SHOULD be released, fixing the + vague part. + + * Let's try to avoid changing the format of the specification after it has + been released, as this will "break the diffs". diff --git a/change-proposals.md b/change-proposals.md index 5c96c3e..2cd02aa 100644 --- a/change-proposals.md +++ b/change-proposals.md @@ -4,21 +4,29 @@ Rules for Submitting API Change Proposals [What is the status of this document?](statuses.md) -How to propose a change to an [draft](statuses.md) API? ----------------------------------------------------------------- +How to propose a change to a [draft](statuses.md) API? +------------------------------------------------------ -Every API repository has an integrated issue tracker: + * Option 1. Start a new thread in our issue tracker (TODO: the location of the + tracker is yet to be agreed upon.) Please make sure to select a proper + project and assign a proper category to your ticket. - * The author of the API (and all other watchers) will be notified when you a - submit a new issue to the tracker. + The author of the API (and all other watchers) SHOULD watch for changes in + their projects and should be notified when you submit a new issue to the + tracker. - * If you want, you can also fork the repository and attach a pull request to - your issue. Since it's a draft, the author may merge such pull requests at - will (he doesn't need to consult any of the partners yet). + * Option 2. You can also fork the repository, change what you want changes, + and send a GitHub pull request. Since it's a draft, the author may merge + such pull requests at will (he doesn't need to consult any of the partners + yet). + + If your pull request is complicated, consider creating a separate issue page + for tracking it. Pull requests are NOT the proper place for longer + discussions - these SHOULD be conducted within the issue tracker. How to propose a change to [released](statuses.md) API? ----------------------------------------------------------------- +------------------------------------------------------- * If you're not the API author, just do the same, as with the draft APIs (described above). @@ -31,11 +39,10 @@ How to propose a change to [released](statuses.md) API? before merging them. -How to get my [draft](statuses.md) or [change proposal](statuses.md) -[released](statuses.md)? --------------------------------------------------------------------- +How to get my `draft` or `change proposal` `released`? +------------------------------------------------------ -You CANNOT assume that all partners are watching repository's issues. You +You CANNOT assume that all partners are watching all of the issues. You MUST contact all the partners **directly** before you can deem your proposal as ready to be released. @@ -46,10 +53,12 @@ ready to be released. * Non-breaking changes to existing releases MAY be deemed as implicitly accepted no sooner than **1 week** after they have been proposed (and no "veto" was received), but this time span SHOULD be extended if there is - reason to suspect some partners may don't like it. + reason to suspect some partners may don't like the change. * Upgrading [draft](statuses.md) to a [release candidate](statuses.md) MUST be - explicitly accepted by all the partners. + explicitly accepted by all the partners. Release candidates will be + periodically upgraded to releases (and assigned version numbers) by project + owners. * All [change proposals](statuses.md) MUST be accompanied by a pull request. Partners MUST be able to review a diff of all changes, and comment on this diff --git a/repos.md b/repos.md index 6d86b11..38f6615 100644 --- a/repos.md +++ b/repos.md @@ -17,9 +17,10 @@ documentation for developers: to diff the changes in the documentation (e.g. "what has changed between versions 1.0.0 and 1.2.7?") is a very important feature. - * GitHub features include an integrated code review tools, issue tracker, - change notifications, automated build tools... and many others, all useful - in such projects (even in documentation-only projects!). + * GitHub features include an integrated code review tools, issue trackers + (we have not decided to use GitHub's issue tracker yet!), change + notifications, automated build tools... and many others, all useful in such + projects (even in documentation-only projects!). Why separate API repositories? @@ -49,6 +50,5 @@ them in separate GitHub repositories: on each API. This allows the partners to easily spot backward-incompatible changes which may break their implementations. - * It allows the project leaders to choose separate teams for working with - separate APIs. Each team will have its own issue tracker and will be in - charge of assigning Git push permissions. + * It allows the project leaders to choose and menage separate teams for + working with separate APIs. diff --git a/statuses.md b/statuses.md index a958d4c..ee2d07c 100644 --- a/statuses.md +++ b/statuses.md @@ -11,7 +11,7 @@ Available statuses this document. It has not been approved (nor anyone was asked to approve it), but - since it's online - everyone may comment on it. -* **CHANGE PROPOSAL** - A document is a copy of other document with a set of +* **CHANGE PROPOSAL** - A document is a copy of another document with a set of changes applied. The partners are asked to comment on the *changed* parts of the document. @@ -37,7 +37,7 @@ The status of a document is determined from its **location and context**: **RELEASED**. * If a document has been tagged with a Git version tag, but there exists a - newer tag of this document, then its status is **OBSOLETE**. + newer tag of this document, then its status is **OUTDATED**. * If a document has been merged into the `stable` branch of one of the official repositories - then the status of this documented is **RELEASE From 9b2feaf19564213a9d2878dec9e25877bf9a714b Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Mon, 11 Jan 2016 16:23:16 +0100 Subject: [PATCH 03/14] Multiple changes * Merge all the docs into a single file. * Move some parts to other documents. * Large number of changes to existing parts. --- README.md | 339 +++++++++++++++++++++++++++++++++++++++----- api-design.md | 97 ------------- change-proposals.md | 71 ---------- partners.md | 12 -- repos.md | 54 ------- statuses.md | 53 ------- 6 files changed, 307 insertions(+), 319 deletions(-) delete mode 100644 api-design.md delete mode 100644 change-proposals.md delete mode 100644 partners.md delete mode 100644 repos.md delete mode 100644 statuses.md diff --git a/README.md b/README.md index 9787a06..7ea00bc 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,81 @@ -Erasmus Without Paper (EWP) - Technical Documentation -===================================================== +Working with EWP Technical Documentation +======================================== -[What is the status of this document?](statuses.md) +This document is our proposal on **how** to work with the technical +documentation within the EWP project (where to store it, how to submit change +proposals, etc.). +* [What is the status of this document?][statuses] +* [See the index of all other EWP Specifications][develhub] -Preamble --------- -This page is written by developers and **for developers**. You'll need to have -experience with Git to be able to work with GitHub properly. +The Structure of EWP Repositories +--------------------------------- - * If you are not a developer, please assign a developer from your team to - keep track of all changes to EWP pages (just click the "Watch" button in - the header of the subprojects you want to watch). +### How documentation is divided? - * These developers MUST be able to propose new changes to the API and accept - API change proposals from other developers in the name of the partner (we - will provide each other ample time for reading all the proposed changes). + * Each section of the documentation is stored in **separate repository**. -**Erasmus Without Paper (EWP)** project aims to ease exchanging data on student -mobility between computer systems in different countries. In order to join EWP, -you will need to implement a subset of its APIs. We require all partners to -follow some basic rules described in the documents below. + * The index of all documents (along with their current statuses) can be found + [at this URL][develhub]. This index SHOULD be frequently updated. + * Some of these documents will probably not change much after their first + release, while some others (like the APIs) will probably keep mutating + (perhaps even after the project is finished - in a backward-compatible way). -Rules for working with technical docs within EWP ------------------------------------------------- -These documents are our proposals on **how** to work with the technical -documentation within the EWP project (where to store it, how to submit change -proposals, etc.). These documents are currently DRAFTs only, and need to be -reviewed and accepted by all the partners before we start defining APIs. +### Why separate API repositories? + +We chose to split EWP requirements into a couple of separate APIs, and host +them in separate GitHub repositories: + + * We believe that all partners should have the option to implement just + a **subset** of all the features we have documented. This will make it + easier for them to start off, claim that they have parts of EWP properly + implemented, and then implement other parts later (possibly *much* later, + by other team of developers). + + * Having each API in **separate repository** has some great advantages, when + it comes to versioning: + + - If a partner does not implement *API X*, then he also knows that he may + ignore all the changes in *API X*'s repository. + + - If a partner has already implemented *API Y* and wants to upgrade his + implementation to include some new changes in new API release, he may + simply review a diff (and/or release notes) in the Git repository between + specific tags. + + - It allows us to use [semantic versioning](http://semver.org/) separately + for each API. This allows the partners to easily spot + backward-incompatible changes which may break their implementations. + + * It even allows the project leaders to choose and manage separate teams for + working with separate APIs. + + +### Why GitHub? + +We chose to use Git and GitHub as the primary tool for working and hosting API +documentation for developers: + + * All developers are familiar with Git. Many developers are also familiar with + GitHub. - * [The Structure of EWP Repositories](repos.md) - * [Rules for API Design, Usage and Versioning](api-design.md) - * [Determining the statuses of documents](statuses.md) - * [Rules for Submitting API Change Proposals](change-proposals.md) - * [The list of developer representatives of EWP partners](partners.md) - * [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) + * Git allows us to easily keep track of all the changes. Having the option + to produce a set of changes between particular versions of the documentation + (e.g. "what has changed between versions `1.0.0` and `1.2.7`?") is a very + important feature, and it can be easily achieved with Git. + * GitHub features include an integrated code review tools, issue trackers, + change notifications, automated build tools - and many others, all useful in + such projects (even in "documentation-only" projects). -Issue tracker? --------------- -*The location of the issue tracker is yet to be agreed upon.* +Issue tracker +------------- + +*WRTODO: The location of the issue tracker is yet to be agreed upon.* GitHub offers built-in issue tracking which would be entirely sufficient for purposes of developing the software and its documentation. However: @@ -58,3 +90,246 @@ purposes of developing the software and its documentation. However: * We SHOULD have only one issue tracker. Having multiple issue trackers might lead to confusion. E.g. a term "issue #123" might become ambiguous. + * Some WPs declared that they will be using Redmine for their own purposes. + We believe it would in everyone's best interest if we at least tried to use + the same Redmine instance for tracking our issues too. + + +Rules for API Design and Versioning +----------------------------------- + +### Semantic Versioning + +We will use **Semantic Versioning** for releases of EWP technical +documentation. It has enormous advantages, when it comes to working (and +reworking) API design: + + * It allows us to tag specific API versions as officially approved. + + * It allows the developers to easily determine when a breaking change occurs + in a particular API, and adapt properly. + + * It follows [a set of quite explicit rules](http://semver.org/). Please get + familiar with them (especially if you plan to design parts of the APIs). + + * Combined with the requirement of preparing an explicit and strict API + specifications, it allows us to easily answer the question: **if it doesn't + work then who's fault is that?** + + +### Use permalinks! + +Whenever you post a link to a document somewhere, you SHOULD use a Git tag +name (or a commit ID) in the posted URL. You should avoid posting links to the +`master` branch (which can mutate, even to the point of having the link +broken). + +Try pressing y key on GitHub site to get a permalink ([other useful +keyboard shortcuts](https://help.github.com/articles/using-keyboard-shortcuts/)). + + +### Backward-compatibility + + * As required by the rules of [semantic versioning](http://semver.org/), all + [breaking changes](https://en.wiktionary.org/wiki/breaking_change) (aka + backward-incompatible changes) SHOULD force the **major** API version number + to be increased (e.g. `1.3.7` should become `2.0.0`). + + * API designers MUST take care of [backward-compatibility rules] + [backward-compatibility-rules], to facilitate predictable workflow for all + implementers. + + * Once a document is [released][statuses], backward-incompatible changes + SHOULD be avoided (if possible). + + * All non-trivial changes (especially the backward-incompatible ones) must go + through the proposal acceptance process, as described in the + [Rules for Submitting API Change Proposals](#change-proposals) section. + + +### Changelogs (aka Release Notes) + +Once a document is [released][statuses], every subsequent release of such +document MUST be accompanied by a *changelog*. All changes SHOULD be noted in +this changelog (and *backward-incompatible* changes should be additionally +highlighted). + +Please note, that this requirement is for **released** documents only, and it +does not imply the need of having a changelog for [change proposals] +[statuses]. Before accepting a proposal, a partner SHOULD review the full +diff of the proposed change. + + +### Preferred Data Formats + +*WRTODO: The preferred data format is yet to be decided upon.* + + * XML? (our recommendation) + * JSON? + + +### Preferred Documentation Format + +*WRTODO: The preferred documentation format is yet to be decided upon.* + + * Markdown? (our recommendation) + * reStructuredText? + * JSON Schema? + * XML Schema? (our recommendation) + +Regardless of what we choose, we do have some requirements on the documentation +itself: + + * We require all API specifications to be **explicit and strict** (with lots + of "MUSTs" and "MUST NOTs" and detailed explanations for all the + enumerations used). If any part of the specifications turns out to be vague, + then a new version of such specification SHOULD be released, fixing the + vague part. + + * Let's try to avoid changing the format of the specification after it has + been first released (as this would "break the diffs"). + + + + +Document statuses +----------------- + +### Available statuses + +* **DRAFT** - designers are still working on this document. It has not been + approved, but everyone may comment on it. + +* **CHANGE PROPOSAL** - A document is a copy of another document with a set of + changes applied. The partners are asked to comment on the *changed* parts of + the document (e.g. when compared to the latest release). + +* **RELEASE CANDIDATE** - All partners have approved the contents of the + document, but it has not been officially released yet (it has no version + number assigned). + +* **RELEASED** - All partners have approved the document and it has been + assigned a version number (e.g. 1.0.0). + +* **OUTDATED** - The document has been made obsolete by a newer release (and + the newer release MAY be backward-incompatible with this document). + +If you're having trouble, taking a look [here][develhub] might also help. + + +### How to determine the status of a document? + +The status of a document is determined from its **location and context**: + + * If a document has been tagged with a Git version tag (such as `v1.0.0`) + in one of the official repositories, and there is no newer release of this + document (no version with a greater tag name) then its status is + **RELEASED**. + + * If a document has been tagged with a Git version tag, but there exists a + newer release tag of its repository, then the document's status is + **OUTDATED**. + + * If a document has been merged into the `stable` branch of one of the + official repositories - then the status of this documented is **RELEASE + CANDIDATE**. + + * If a document has not been merged into the `stable` branch yet, but there + already exists an appropriate open pull request for its merging - then the + status of this documented is **CHANGE PROPOSAL**. + + * In all other cases - the document is a **DRAFT**. + +"Official repositories" are the ones owned by the **erasmus-without-paper** +GitHub organization. + + + + +Rules for Submitting API Change Proposals +----------------------------------------- + +### How to propose a change to a [draft][statuses] API? + + * Option 1. Start a new thread in our issue tracker (WRTODO: put a link to the + tracker here.) Please make sure to select a proper project and assign a + proper category to your ticket. + + The author of the API (and all other watchers) SHOULD watch for changes in + their projects and should be notified when you submit a new issue to the + tracker. + + * Option 2. You can also fork the repository, change what you want changed, + and send a GitHub pull request. Since it's a draft, the author may merge + such pull requests at will (he doesn't need to consult any of the partners + yet). + + If your pull request is complicated, consider creating a separate issue page + for tracking it. Pull requests are NOT the proper place for longer + discussions - these SHOULD be conducted within the issue tracker. + + +### How to propose a change to [released][statuses] API? + + * If you're not the API author, just do the same, as with the draft APIs + (described above). + + * If you are the API author yourself, you can push your proposed changes to a + separate branch (or fork), then issue yourself a pull request. + + * Only trivial changes of accepted APIs may be merged without asking for the + approval of the other partners. All non-trivial proposals SHOULD be accepted + before merging them. + + +### How to get my draft (or change proposal) released? + +You CANNOT assume that all partners are watching all of the issues. You +MUST contact all the partners and attempt to get their approval before you can +deem your proposal as ready to be released. + + * [Breaking changes](https://en.wiktionary.org/wiki/breaking_change) to + existing [releases][statuses] MUST be explicitly accepted by all + the partners. + + * Non-breaking changes to existing releases MAY be deemed as implicitly + accepted no sooner than **1 week** after they have been proposed (and no + "veto" was received), but this time span SHOULD be extended if there is + reason to suspect some partners may don't like the change. + + * Upgrading [draft][statuses] to a [release candidate][statuses] MUST be + explicitly accepted by all the partners. + + * Release candidates will be periodically upgraded to releases (and assigned + version numbers) by project managers. + + * All [change proposals][statuses] SHOULD be accompanied by a pull request. + Partners MUST be able to review a diff of all changes, and comment on this + diff. + + +EWP Partner Developers +---------------------- + +This is the list of developers who are allowed to accept the API change +proposals in the name of a partner: + +* **Poland**: + + * Wojciech Rygielski - rygielski@mimuw.edu.pl + * Michał Kurzydłowski - michalk@mimuw.edu.pl + +* *(WRTODO: full list of the partners)* + + +Relevant external documents +--------------------------- + + * [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) - strict definitions of + keywords such as "MUST" and "SHOULD" (which we will use throughout all the + documents). + + +[develhub]: http://developers.erasmuswithoutpaper.eu/ +[statuses]: https://github.com/erasmus-without-paper/ewp-specs-management/blob/master/README.md#statuses +[backward-compatibility-rules]: https://github.com/erasmus-without-paper/ewp-specs-architecture/blob/master/README.md#backward-compatibility-rules diff --git a/api-design.md b/api-design.md deleted file mode 100644 index 545fdc3..0000000 --- a/api-design.md +++ /dev/null @@ -1,97 +0,0 @@ -Rules for API Design, Usage and Versioning -========================================== - -[What is the status of this document?](statuses.md) - - -Semantic Versioning -------------------- - -We use **Semantic Versioning** in all our API documentation. It has enormous -advantages, when it comes to working (and reworking) API design: - - * It allows us to tag specific API versions as officially approved. - - * It allows the developers to easily determine when a breaking change occurs - in a particular API, and adapt properly. - - * It follows [a set of quite explicit rules](http://semver.org/). Please get - familiar with them (especially if you plan to design parts of the APIs). - - * Combined with the requirement of preparing a explicit and strict API - specifications, it allows us to easily answer the question: **if it doesn't - work then who's fault is that?** - - -Permalinks ----------- - -Whenever you post a new release of an API somewhere, you SHOULD use a Git tag -name (or a commit ID) in the posted URL. You should avoid posting links to the -`master` branch (which can mutate, even to the point of having the link -broken). - -Try pressing y key on GitHub site to get a permalink ([other useful -keyboard shortcuts](https://help.github.com/articles/using-keyboard-shortcuts/)). - - -Backward-compatibility ----------------------- - -As required by the rules of [semantic versioning](http://semver.org/), all -[breaking changes](https://en.wiktionary.org/wiki/breaking_change) (aka -backward-incompatible changes) SHOULD force the MAJOR API version number to be -increased. - -Once a document is [released](statuses.md), such backward-incompatible -changes SHOULD be avoided (is possible). - -All non-trivial changes (especially the backward-incompatible ones!) must go -through the proposal acceptance process, as described in the -[Rules for Submitting API Change Proposals](change-proposals.md) document. - - -Changelogs (aka Release Notes) -------------------------------- - -Once an API is [released](statuses.md), every subsequent release of this API -MUST be accompanied by a *changelog*. All changes SHOULD be noted in this -changelog (and *backward-incompatible* changes should be additionally -highlighted). - -Please note, that this requirement is for **released** documents only, and it -does not imply the need of having a changelog for [change proposals] -(statuses.md). Before accepting a proposal, a partner SHOULD review the full -diff of the proposed change. - - -Preferred Data Format ---------------------- - -*The preferred data format is yet to be decided upon.* - - * XML? - * JSON? - - -Preferred Documentation Format ------------------------------- - -*The preferred documentation format is yet to be decided upon.* - - * Markdown? - * reStructuredText? - * JSON Schema? - * XML Schema? - -However, regardless of what we choose, we do have some requirements on the -documentation itself: - - * We require all API specifications to be **explicit and strict** (with lots - of "MUSTs" and "MUST NOTs" and detailed explanations for all the - enumerations used). If any part of the specifications turns out to be vague, - then a new version of such specification SHOULD be released, fixing the - vague part. - - * Let's try to avoid changing the format of the specification after it has - been released, as this will "break the diffs". diff --git a/change-proposals.md b/change-proposals.md deleted file mode 100644 index 2cd02aa..0000000 --- a/change-proposals.md +++ /dev/null @@ -1,71 +0,0 @@ -Rules for Submitting API Change Proposals -========================================= - -[What is the status of this document?](statuses.md) - - -How to propose a change to a [draft](statuses.md) API? ------------------------------------------------------- - - * Option 1. Start a new thread in our issue tracker (TODO: the location of the - tracker is yet to be agreed upon.) Please make sure to select a proper - project and assign a proper category to your ticket. - - The author of the API (and all other watchers) SHOULD watch for changes in - their projects and should be notified when you submit a new issue to the - tracker. - - * Option 2. You can also fork the repository, change what you want changes, - and send a GitHub pull request. Since it's a draft, the author may merge - such pull requests at will (he doesn't need to consult any of the partners - yet). - - If your pull request is complicated, consider creating a separate issue page - for tracking it. Pull requests are NOT the proper place for longer - discussions - these SHOULD be conducted within the issue tracker. - - -How to propose a change to [released](statuses.md) API? -------------------------------------------------------- - - * If you're not the API author, just do the same, as with the draft APIs - (described above). - - * If you are the API author yourself, you can push your proposed changes to a - separate branch (or fork), then issue yourself a pull request. - - * Only trivial changes of accepted APIs may be merged without asking for the - approval of the other partners. All non-trivial proposals SHOULD be accepted - before merging them. - - -How to get my `draft` or `change proposal` `released`? ------------------------------------------------------- - -You CANNOT assume that all partners are watching all of the issues. You -MUST contact all the partners **directly** before you can deem your proposal as -ready to be released. - - * [Breaking changes](https://en.wiktionary.org/wiki/breaking_change) to - existing [releases](statuses.md) MUST be explicitly accepted by all - the partners. - - * Non-breaking changes to existing releases MAY be deemed as implicitly - accepted no sooner than **1 week** after they have been proposed (and no - "veto" was received), but this time span SHOULD be extended if there is - reason to suspect some partners may don't like the change. - - * Upgrading [draft](statuses.md) to a [release candidate](statuses.md) MUST be - explicitly accepted by all the partners. Release candidates will be - periodically upgraded to releases (and assigned version numbers) by project - owners. - - * All [change proposals](statuses.md) MUST be accompanied by a pull request. - Partners MUST be able to review a diff of all changes, and comment on this - diff. - - -How to contact the partners "directly"? ---------------------------------------- - -*To be decided.* diff --git a/partners.md b/partners.md deleted file mode 100644 index f5ec37b..0000000 --- a/partners.md +++ /dev/null @@ -1,12 +0,0 @@ -The list of developer representatives of EWP partners -===================================================== - -This is the list of developers who are allowed to accept the API change -proposals in the name of a partner: - -* **Poland**: - - * Wojciech Rygielski - rygielski@mimuw.edu.pl - * Michał Kurzydłowski - michalk@mimuw.edu.pl - -* *(full list of partners - TODO)* diff --git a/repos.md b/repos.md deleted file mode 100644 index 38f6615..0000000 --- a/repos.md +++ /dev/null @@ -1,54 +0,0 @@ -The Structure of EWP Repositories -================================= - -[What is the status of this document?](statuses.md) - - -Why GitHub? ------------ - -We chose to use GitHub as the primary tool for working and hosting API -documentation for developers: - - * All developers are familiar with Git. Many developers are also familiar with - GitHub. - - * GitHub allows us to easily keep track of all the changes. Having the option - to diff the changes in the documentation (e.g. "what has changed between - versions 1.0.0 and 1.2.7?") is a very important feature. - - * GitHub features include an integrated code review tools, issue trackers - (we have not decided to use GitHub's issue tracker yet!), change - notifications, automated build tools... and many others, all useful in such - projects (even in documentation-only projects!). - - -Why separate API repositories? ------------------------------- - -We chose to split EWP requirements into a couple of separate APIs, and host -them in separate GitHub repositories: - - * We believe that all partners should have the option to implement just - a **subset** of all the features we have documented. This will make it - easier for them to start off, claim that they have parts of EWP properly - implemented, and then implement other parts later (possibly much later, with - other teams of developers). - - * Having each API in **separate repository** has some great advantages, when - it comes to versioning: - - - If a partner does not implement *API X*, then he also knows that he may - ignore all the changes in *API X*'s repository. - - - If a partner have already implemented *API Y* and wants to upgrade his - implementation to include some new changes in new API release, he may - simply review a diff (and/or release notes) in the Git repository between - specific tags. - - - It allows us to use [semantic versioning](http://semver.org/) separately - on each API. This allows the partners to easily spot backward-incompatible - changes which may break their implementations. - - * It allows the project leaders to choose and menage separate teams for - working with separate APIs. diff --git a/statuses.md b/statuses.md deleted file mode 100644 index ee2d07c..0000000 --- a/statuses.md +++ /dev/null @@ -1,53 +0,0 @@ -Document statuses -================= - -[What is the status of this document?](statuses.md) - - -Available statuses ------------------- - -* **DRAFT** - A designer (or a small group of designers) are still working on - this document. It has not been approved (nor anyone was asked to approve it), - but - since it's online - everyone may comment on it. - -* **CHANGE PROPOSAL** - A document is a copy of another document with a set of - changes applied. The partners are asked to comment on the *changed* parts of - the document. - -* **RELEASE CANDIDATE** - All partners have approved the contents of the - document, but it has not been officially released yet (it has no version - number assigned). - -* **RELEASED** - All partners have approved the document and it has been - assigned a version number (e.g. 1.0.0). - -* **OUTDATED** - The document has been made obsolete by a newer release (and - the newer release MAY be backward-incompatible with this document). - - -How to determine the status of a document? ------------------------------------------- - -The status of a document is determined from its **location and context**: - - * If a document has been tagged with a Git version tag (such as `v1.0.0`) - in one of the official repositories, and there is no newer release of this - document (no version with a greater tag name) then its status is - **RELEASED**. - - * If a document has been tagged with a Git version tag, but there exists a - newer tag of this document, then its status is **OUTDATED**. - - * If a document has been merged into the `stable` branch of one of the - official repositories - then the status of this documented is **RELEASE - CANDIDATE**. - - * If a document has not been merged into the `stable` branch yet, but there - already exists an appropriate open pull request for its merging - then the - status of this documented is **CHANGE PROPOSAL**. - - * In all other cases - the document is a **DRAFT**. - -Official repositories are the ones owned by the **erasmus-without-paper** -GitHub organization. From 136fd5c1417b0a2028b40e85bb5c069bec706c62 Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Tue, 12 Jan 2016 21:08:25 +0100 Subject: [PATCH 04/14] Describe DEPRECATED status --- README.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7ea00bc..40be7a9 100644 --- a/README.md +++ b/README.md @@ -211,10 +211,15 @@ Document statuses * **RELEASED** - All partners have approved the document and it has been assigned a version number (e.g. 1.0.0). +Additionally, RELEASED documents may also be: + * **OUTDATED** - The document has been made obsolete by a newer release (and the newer release MAY be backward-incompatible with this document). -If you're having trouble, taking a look [here][develhub] might also help. +* **DEPRECATED** - The document is at its latest version, but the entire API + (described by this document) has been deprecated, and probably replaced by + some other API. Such documents SHOULD explain (inside their contents) *why* + they are deprecated, and which other APIs replace them. ### How to determine the status of a document? @@ -230,6 +235,10 @@ The status of a document is determined from its **location and context**: newer release tag of its repository, then the document's status is **OUTDATED**. + * The document is **DEPRECATED** only when its *latest release* explicitly + states that its contents are deprecated. (This also means that it *is* + possible to *undeprecate* a document.) + * If a document has been merged into the `stable` branch of one of the official repositories - then the status of this documented is **RELEASE CANDIDATE**. From 0132498305eccde091e30760a6345f5499b547f8 Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Fri, 15 Jan 2016 18:17:03 +0100 Subject: [PATCH 05/14] Rules for xmlns and stable branches naming --- README.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 40be7a9..9e99c8f 100644 --- a/README.md +++ b/README.md @@ -147,6 +147,23 @@ keyboard shortcuts](https://help.github.com/articles/using-keyboard-shortcuts/)) [Rules for Submitting API Change Proposals](#change-proposals) section. +### XML namespaces and branches + + * All released specifications MUST be merged to a `stable-v` branch, where + *N* is the major version number of the specification (ideally, *N* will + stay equal to `1` for the majority of all specifications). + + * XML namespaces used throughout the project SHOULD "self-describe" + themselves. Namespace values SHOULD be valid GitHub URLs, pointing to + `stable-*` GitHub branches. Every XML document SHOULD conform to the + specification described in the `stable-*` branch given in its XML namespace. + + * Major changes in API versions SHOULD lead to a new `stable-*` (e.g. + `stable-v2`) branch being created. If there is any XML namespace associated + with API, then this also means that a new XML namespace will be created (and + newer versions of XML documents will be required to use this namespace). + + ### Changelogs (aka Release Notes) Once a document is [released][statuses], every subsequent release of such @@ -239,11 +256,11 @@ The status of a document is determined from its **location and context**: states that its contents are deprecated. (This also means that it *is* possible to *undeprecate* a document.) - * If a document has been merged into the `stable` branch of one of the + * If a document has been merged into the `stable-*` branch of one of the official repositories - then the status of this documented is **RELEASE CANDIDATE**. - * If a document has not been merged into the `stable` branch yet, but there + * If a document has not been merged into the `stable-*` branch yet, but there already exists an appropriate open pull request for its merging - then the status of this documented is **CHANGE PROPOSAL**. From a09927bc4cf92b4d903efef0ee081701ecfc89c1 Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Fri, 15 Jan 2016 19:04:55 +0100 Subject: [PATCH 06/14] We're not yet so sure we prefer XML Schemas over JSON --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9e99c8f..49656e1 100644 --- a/README.md +++ b/README.md @@ -181,7 +181,7 @@ diff of the proposed change. *WRTODO: The preferred data format is yet to be decided upon.* - * XML? (our recommendation) + * XML? (our current pick) * JSON? @@ -189,10 +189,10 @@ diff of the proposed change. *WRTODO: The preferred documentation format is yet to be decided upon.* - * Markdown? (our recommendation) + * Markdown? (our current pick) * reStructuredText? * JSON Schema? - * XML Schema? (our recommendation) + * XML Schema? (our current pick) Regardless of what we choose, we do have some requirements on the documentation itself: From 2c58a75ba454d8b4062e148fa8c0440e78e80e82 Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Fri, 15 Jan 2016 19:13:04 +0100 Subject: [PATCH 07/14] Xmlns naming rules for draft APIs --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 49656e1..284f4bf 100644 --- a/README.md +++ b/README.md @@ -163,6 +163,9 @@ keyboard shortcuts](https://help.github.com/articles/using-keyboard-shortcuts/)) with API, then this also means that a new XML namespace will be created (and newer versions of XML documents will be required to use this namespace). + * Unreleased (draft) APIs also SHOULD use valid GitHub URLs for theirs XML + namespaces (most probably, URLs referring to the `master` branch). + ### Changelogs (aka Release Notes) From 53ab9a3ed64f0c724c8abbfa87974ee480e836d1 Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Mon, 18 Jan 2016 12:36:19 +0100 Subject: [PATCH 08/14] Less formal document statuses, other minor changes --- README.md | 213 ++++++++++++++++++++++++------------------------------ 1 file changed, 95 insertions(+), 118 deletions(-) diff --git a/README.md b/README.md index 284f4bf..57f71dc 100644 --- a/README.md +++ b/README.md @@ -12,16 +12,17 @@ proposals, etc.). The Structure of EWP Repositories --------------------------------- -### How documentation is divided? +### How documentation is to be divided? - * Each section of the documentation is stored in **separate repository**. + * Separate sections of the documentation SHOULD be stored in **separate + Git repositories**. - * The index of all documents (along with their current statuses) can be found - [at this URL][develhub]. This index SHOULD be frequently updated. + * The index of all documents (along with their current statuses) SHOULD be + kept [at this URL][develhub]. If SHOULD be frequently updated. - * Some of these documents will probably not change much after their first - release, while some others (like the APIs) will probably keep mutating - (perhaps even after the project is finished - in a backward-compatible way). +Some of these repositories will probably not change much after their first +release, while some others (like the APIs) will probably keep mutating perhaps +even after the project is finished (though, in a backward-compatible way). ### Why separate API repositories? @@ -29,11 +30,11 @@ The Structure of EWP Repositories We chose to split EWP requirements into a couple of separate APIs, and host them in separate GitHub repositories: - * We believe that all partners should have the option to implement just - a **subset** of all the features we have documented. This will make it - easier for them to start off, claim that they have parts of EWP properly - implemented, and then implement other parts later (possibly *much* later, - by other team of developers). + * We believe that partners (this includes all the **future** partners) should + have the option to implement just a **subset** of all the features we have + documented. This will make it easier for them to start off, claim that they + have parts of EWP properly implemented, and then implement other parts later + (possibly *much* later, with other teams of developers). * Having each API in **separate repository** has some great advantages, when it comes to versioning: @@ -50,17 +51,19 @@ them in separate GitHub repositories: for each API. This allows the partners to easily spot backward-incompatible changes which may break their implementations. - * It even allows the project leaders to choose and manage separate teams for + * It allows the project leaders to choose and manage separate teams for working with separate APIs. ### Why GitHub? -We chose to use Git and GitHub as the primary tool for working and hosting API -documentation for developers: +We chose to use Git and GitHub as the primary tool for working and hosting +*documentation for developers*: * All developers are familiar with Git. Many developers are also familiar with - GitHub. + GitHub. **We will require developers to review and accept documentation + often** throughout the project. We believe that these tools will help them + with this task. * Git allows us to easily keep track of all the changes. Having the option to produce a set of changes between particular versions of the documentation @@ -68,8 +71,10 @@ documentation for developers: important feature, and it can be easily achieved with Git. * GitHub features include an integrated code review tools, issue trackers, - change notifications, automated build tools - and many others, all useful in - such projects (even in "documentation-only" projects). + change notifications, automated build tools - and many other features. We + are aware that our most of the repositories will be hosting documentation + only, but we do find all these tools useful even in documentation-only + projects. Issue tracker @@ -104,28 +109,19 @@ We will use **Semantic Versioning** for releases of EWP technical documentation. It has enormous advantages, when it comes to working (and reworking) API design: - * It allows us to tag specific API versions as officially approved. + * We will assign documents their version numbers only after they are + officially approved. - * It allows the developers to easily determine when a breaking change occurs - in a particular API, and adapt properly. + * Semantic versioning scheme allows developers to easily determine when a + breaking change occurs in a particular API. * It follows [a set of quite explicit rules](http://semver.org/). Please get familiar with them (especially if you plan to design parts of the APIs). - * Combined with the requirement of preparing an explicit and strict API - specifications, it allows us to easily answer the question: **if it doesn't - work then who's fault is that?** - - -### Use permalinks! - -Whenever you post a link to a document somewhere, you SHOULD use a Git tag -name (or a commit ID) in the posted URL. You should avoid posting links to the -`master` branch (which can mutate, even to the point of having the link -broken). - -Try pressing y key on GitHub site to get a permalink ([other useful -keyboard shortcuts](https://help.github.com/articles/using-keyboard-shortcuts/)). + * Having a single, official latest version of the document, combined with the + requirement of preparing an explicit and strict API specifications, allows us + to easily answer the question: **if it doesn't work then who's fault is + that?** ### Backward-compatibility @@ -140,14 +136,16 @@ keyboard shortcuts](https://help.github.com/articles/using-keyboard-shortcuts/)) implementers. * Once a document is [released][statuses], backward-incompatible changes - SHOULD be avoided (if possible). + SHOULD be avoided. Once first implementations are deployed on production + servers, backward-incompatible changes MUST NOT occur, unless they cannot be + avoided. * All non-trivial changes (especially the backward-incompatible ones) must go through the proposal acceptance process, as described in the [Rules for Submitting API Change Proposals](#change-proposals) section. -### XML namespaces and branches +### Git branches (and XML namespaces) * All released specifications MUST be merged to a `stable-v` branch, where *N* is the major version number of the specification (ideally, *N* will @@ -169,15 +167,15 @@ keyboard shortcuts](https://help.github.com/articles/using-keyboard-shortcuts/)) ### Changelogs (aka Release Notes) -Once a document is [released][statuses], every subsequent release of such -document MUST be accompanied by a *changelog*. All changes SHOULD be noted in -this changelog (and *backward-incompatible* changes should be additionally -highlighted). + * Once a document is [released][statuses], every subsequent release of such + document MUST be accompanied by a *changelog*. All changes SHOULD be noted + in this changelog (and *backward-incompatible* changes should be + additionally highlighted). Please note, that this requirement is for **released** documents only, and it -does not imply the need of having a changelog for [change proposals] -[statuses]. Before accepting a proposal, a partner SHOULD review the full -diff of the proposed change. +does not imply the need of having a detailed changelog made for every [change +proposal][statuses] (although many change proposals MAY be accompanied by such +change logs). ### Preferred Data Formats @@ -210,64 +208,58 @@ itself: been first released (as this would "break the diffs"). - - -Document statuses ------------------ - -### Available statuses - -* **DRAFT** - designers are still working on this document. It has not been - approved, but everyone may comment on it. - -* **CHANGE PROPOSAL** - A document is a copy of another document with a set of - changes applied. The partners are asked to comment on the *changed* parts of - the document (e.g. when compared to the latest release). +### Use permalinks! -* **RELEASE CANDIDATE** - All partners have approved the contents of the - document, but it has not been officially released yet (it has no version - number assigned). +Whenever you post a link to a specific version of a document somewhere, you +SHOULD use a Git tag name (or a commit ID) in the posted URL. You should avoid +posting links to the `master` branch (which can mutate, even to the point of +having the link broken). -* **RELEASED** - All partners have approved the document and it has been - assigned a version number (e.g. 1.0.0). +*Hint:* Try pressing y key on GitHub site to get a permalink ([other +useful keyboard shortcuts](https://help.github.com/articles/using-keyboard-shortcuts/)). -Additionally, RELEASED documents may also be: -* **OUTDATED** - The document has been made obsolete by a newer release (and - the newer release MAY be backward-incompatible with this document). + -* **DEPRECATED** - The document is at its latest version, but the entire API - (described by this document) has been deprecated, and probably replaced by - some other API. Such documents SHOULD explain (inside their contents) *why* - they are deprecated, and which other APIs replace them. +Document statuses +----------------- +Before you read any EWP document on GitHub, make sure you know the status of +this document. An index of official documents and drafts is kept [here] +[develhub]. You can also attempt determine the status yourself based the +document's **location and context**. -### How to determine the status of a document? +Common document statuses include (but are not limited to): -The status of a document is determined from its **location and context**: + * **RELEASED** - All partners have approved the document and it has been + assigned a version number (e.g. `1.0.0`) in one of the official project + repositories. - * If a document has been tagged with a Git version tag (such as `v1.0.0`) - in one of the official repositories, and there is no newer release of this - document (no version with a greater tag name) then its status is - **RELEASED**. + * If there is no newer release of this document (no version with a greater + tag name) then it is a **Latest release**. - * If a document has been tagged with a Git version tag, but there exists a - newer release tag of its repository, then the document's status is - **OUTDATED**. + * If there exists a newer release of this document, then its status is + **OUTDATED**. The latest release MAY be backward-incompatible with this + document. - * The document is **DEPRECATED** only when its *latest release* explicitly - states that its contents are deprecated. (This also means that it *is* - possible to *undeprecate* a document.) + * It is also possible for a document to be at its latest release, but the + entire API (described by this document) has been **DEPRECATED**, and + probably replaced by some other API. Such documents MUST explain (inside + their contents) *why* they are deprecated, and which other APIs replace + them. (Note, that this definition does not prohibit to *undeprecate* a + document.) - * If a document has been merged into the `stable-*` branch of one of the - official repositories - then the status of this documented is **RELEASE - CANDIDATE**. + * **CHANGE PROPOSAL** - A document is a copy of another document with a set of + changes applied. The partners are asked to comment on the *changed* parts of + the document (e.g. when compared to the latest release). - * If a document has not been merged into the `stable-*` branch yet, but there - already exists an appropriate open pull request for its merging - then the - status of this documented is **CHANGE PROPOSAL**. + Change proposals may appear outside of the official repositories (i.e. in + forks). They are often accompanied by open pull requests for merging them to + official `stable-*` branches. - * In all other cases - the document is a **DRAFT**. + * **DRAFT** - designers are still working on this document. It has not been + approved, but everyone may comment on it. After being reviewed and accepted, + drafts become releases. "Official repositories" are the ones owned by the **erasmus-without-paper** GitHub organization. @@ -278,37 +270,22 @@ GitHub organization. Rules for Submitting API Change Proposals ----------------------------------------- -### How to propose a change to a [draft][statuses] API? +### How to propose a change to a document? - * Option 1. Start a new thread in our issue tracker (WRTODO: put a link to the - tracker here.) Please make sure to select a proper project and assign a + * **Option 1.** Start a new thread in our issue tracker (WRTODO: put a link to + the tracker here.) Please make sure to select a proper project and assign a proper category to your ticket. - The author of the API (and all other watchers) SHOULD watch for changes in - their projects and should be notified when you submit a new issue to the - tracker. + The authors and maintainers of the APIs MUST subscribe for GitHub + notifications for their projects, and should be notified when you submit a + new issue to the tracker. - * Option 2. You can also fork the repository, change what you want changed, - and send a GitHub pull request. Since it's a draft, the author may merge - such pull requests at will (he doesn't need to consult any of the partners - yet). + * **Option 2.** You MAY also fork the repository, change what you want + changed, and send a GitHub pull request. If your pull request is complicated, consider creating a separate issue page for tracking it. Pull requests are NOT the proper place for longer - discussions - these SHOULD be conducted within the issue tracker. - - -### How to propose a change to [released][statuses] API? - - * If you're not the API author, just do the same, as with the draft APIs - (described above). - - * If you are the API author yourself, you can push your proposed changes to a - separate branch (or fork), then issue yourself a pull request. - - * Only trivial changes of accepted APIs may be merged without asking for the - approval of the other partners. All non-trivial proposals SHOULD be accepted - before merging them. + discussions - such discussions SHOULD be conducted within the issue tracker. ### How to get my draft (or change proposal) released? @@ -317,6 +294,9 @@ You CANNOT assume that all partners are watching all of the issues. You MUST contact all the partners and attempt to get their approval before you can deem your proposal as ready to be released. + * Only trivial changes of already implemented APIs may be merged without + asking for the approval of the other partners. + * [Breaking changes](https://en.wiktionary.org/wiki/breaking_change) to existing [releases][statuses] MUST be explicitly accepted by all the partners. @@ -326,15 +306,12 @@ deem your proposal as ready to be released. "veto" was received), but this time span SHOULD be extended if there is reason to suspect some partners may don't like the change. - * Upgrading [draft][statuses] to a [release candidate][statuses] MUST be + * Upgrading [draft][statuses] to a [release candidate][statuses] SHOULD be explicitly accepted by all the partners. - * Release candidates will be periodically upgraded to releases (and assigned - version numbers) by project managers. - * All [change proposals][statuses] SHOULD be accompanied by a pull request. - Partners MUST be able to review a diff of all changes, and comment on this - diff. + Partners MUST be able to review a diff of all changes, and be allowed to + comment on this diff somewhere. EWP Partner Developers From 01db449566e364442a0f3597c53a4ec0be67e617 Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Mon, 18 Jan 2016 18:18:59 +0100 Subject: [PATCH 09/14] Expand additional duties of EWP Developers --- README.md | 51 +++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 37 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 57f71dc..42ab7f7 100644 --- a/README.md +++ b/README.md @@ -290,9 +290,10 @@ Rules for Submitting API Change Proposals ### How to get my draft (or change proposal) released? -You CANNOT assume that all partners are watching all of the issues. You -MUST contact all the partners and attempt to get their approval before you can -deem your proposal as ready to be released. +You CANNOT assume that all partners are watching all of the issues. You MUST +contact all the partners (see the *EWP Partners and Developers* section below) +and attempt to get their approval before you can deem your proposal as ready to +be released. * Only trivial changes of already implemented APIs may be merged without asking for the approval of the other partners. @@ -314,18 +315,40 @@ deem your proposal as ready to be released. comment on this diff somewhere. -EWP Partner Developers ----------------------- - -This is the list of developers who are allowed to accept the API change -proposals in the name of a partner: - -* **Poland**: - - * Wojciech Rygielski - rygielski@mimuw.edu.pl - * Michał Kurzydłowski - michalk@mimuw.edu.pl +EWP Partners and Developers +--------------------------- -* *(WRTODO: full list of the partners)* +While the EWP Project lasts, new specifications will be drafted and released. +This requires all the partners to agree on the contents of these +specifications. Every partner will provide its representatives - developers +which will accept specifications in the name of the partner. + +Some other developers may have some special or additional duties (which should +also be a part of the common knowledge). + +We intend to keep this list here, as part of this document. + + +### Poland + + * Wojciech Rygielski - `rygielski@mimuw.edu.pl`. GitHub username: + [wrygiel](https://github.com/wrygiel) + + **Additional duties:** I am in charge of the [developer's pages][develhub] + and keeping the EWP specifications clean, up-to-date and (if possible) + backward-compatible. I will also be keeping track of which partners have + accepted which documents. In general, I won't be taking part in implementing + the Polish *EWP Host*, but I will probably be implementing the EWP Registry + Service. + + * Michał Kurzydłowski - `michalk@mimuw.edu.pl`. GitHub username: + [Awerin](https://github.com/Awerin). + + **Additional duties:** Michał will be accepting EWP specifications on behalf + of Poland, but he will also be implementing a set of common libraries which + other partners may be wanting to use. + +*(WRTODO: full list of the partners)* Relevant external documents From b26f34a23a662babfd5f1e72f914aace19ec41ee Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Mon, 18 Jan 2016 19:06:50 +0100 Subject: [PATCH 10/14] Add links to the issue tracker --- README.md | 40 +++++++++++++++++----------------------- 1 file changed, 17 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 42ab7f7..8ee10b9 100644 --- a/README.md +++ b/README.md @@ -80,24 +80,18 @@ We chose to use Git and GitHub as the primary tool for working and hosting Issue tracker ------------- -*WRTODO: The location of the issue tracker is yet to be agreed upon.* +GitHub offers built-in issue tracking which should be entirely sufficient for +purposes of developing the software and its documentation. By design, every +GitHub project can have its own separate issue tracker, but we have decided to +use **only one** (to avoid confusion with possibly repeated issue numbers). -GitHub offers built-in issue tracking which would be entirely sufficient for -purposes of developing the software and its documentation. However: +Our official issue tracker can be found here: - * There are also other (external) issue trackers which would also suffice for - this particular purpose. +https://github.com/erasmus-without-paper/issues/issues - * If GitHub turns out to be NOT sufficient for other parts of the EWP project - (and developers are not the only ones who need issue tracking) - then we - SHOULD try to find a common solution which would play out well for everyone. - - * We SHOULD have only one issue tracker. Having multiple issue trackers might - lead to confusion. E.g. a term "issue #123" might become ambiguous. - - * Some WPs declared that they will be using Redmine for their own purposes. - We believe it would in everyone's best interest if we at least tried to use - the same Redmine instance for tracking our issues too. +It's worth noting that WP6 was planning to use Redmine for their own purposes. +This might mean that we'll end up with two separate issue trackers. You may +discuss this issue [here](https://github.com/erasmus-without-paper/issues/issues/1). Rules for API Design and Versioning @@ -272,16 +266,16 @@ Rules for Submitting API Change Proposals ### How to propose a change to a document? - * **Option 1.** Start a new thread in our issue tracker (WRTODO: put a link to - the tracker here.) Please make sure to select a proper project and assign a - proper category to your ticket. + * **Option 1.** Start a new thread in our [issue tracker] + (https://github.com/erasmus-without-paper/issues/issues). Please make sure + to assign fitting labels to your issue. - The authors and maintainers of the APIs MUST subscribe for GitHub - notifications for their projects, and should be notified when you submit a - new issue to the tracker. + The authors and maintainers of the APIs SHOULD subscribe for GitHub's issue + notifications, and should be notified when you submit a new issue to the + tracker. - * **Option 2.** You MAY also fork the repository, change what you want - changed, and send a GitHub pull request. + * **Option 2.** You MAY also [fork](https://guides.github.com/activities/forking/) + the repository, change what you want changed, and send a pull request. If your pull request is complicated, consider creating a separate issue page for tracking it. Pull requests are NOT the proper place for longer From 9fbac05229f59df92801cd5d16b03752a6a1fe7f Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Mon, 18 Jan 2016 21:06:51 +0100 Subject: [PATCH 11/14] Multiple issue trackers --- README.md | 38 +++++++++++++++++++++++--------------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 8ee10b9..db1be01 100644 --- a/README.md +++ b/README.md @@ -81,17 +81,26 @@ Issue tracker ------------- GitHub offers built-in issue tracking which should be entirely sufficient for -purposes of developing the software and its documentation. By design, every -GitHub project can have its own separate issue tracker, but we have decided to -use **only one** (to avoid confusion with possibly repeated issue numbers). +purposes of developing the software and its documentation. -Our official issue tracker can be found here: +Every GitHub project may have its own separate issue tracker, and we have +chosen to stick to this design decision. In other words, we will use **multiple +issue trackers**. When you're reading documentation on GitHub and you find a +bug, simply scroll to the top of the page, and click the *Issues* tab. -https://github.com/erasmus-without-paper/issues/issues +Pros: -It's worth noting that WP6 was planning to use Redmine for their own purposes. -This might mean that we'll end up with two separate issue trackers. You may -discuss this issue [here](https://github.com/erasmus-without-paper/issues/issues/1). + * We keep project's issues along with the project's code. + * The *Issues* tab is always around. + +Cons: + + * Issue numbers will not be unique within the entire EWP Project. When + cross-referencing issues between sub-projects, absolute issue URLs will need + to be used. However, since WP6 will also use a separate issue tracker (and + we were [unable to share it] + (https://github.com/erasmus-without-paper/general-issues/issues/1)), the + issue numbers would not be unique *in either case*. Rules for API Design and Versioning @@ -266,12 +275,11 @@ Rules for Submitting API Change Proposals ### How to propose a change to a document? - * **Option 1.** Start a new thread in our [issue tracker] - (https://github.com/erasmus-without-paper/issues/issues). Please make sure - to assign fitting labels to your issue. + * **Option 1.** Start a new thread in the issue tracker associated with this + document (search for the *Issues* tab on the top of the GitHub page). The authors and maintainers of the APIs SHOULD subscribe for GitHub's issue - notifications, and should be notified when you submit a new issue to the + notifications, and should be notified when you submit a new issue to their tracker. * **Option 2.** You MAY also [fork](https://guides.github.com/activities/forking/) @@ -327,17 +335,17 @@ We intend to keep this list here, as part of this document. * Wojciech Rygielski - `rygielski@mimuw.edu.pl`. GitHub username: [wrygiel](https://github.com/wrygiel) - + **Additional duties:** I am in charge of the [developer's pages][develhub] and keeping the EWP specifications clean, up-to-date and (if possible) backward-compatible. I will also be keeping track of which partners have accepted which documents. In general, I won't be taking part in implementing the Polish *EWP Host*, but I will probably be implementing the EWP Registry Service. - + * Michał Kurzydłowski - `michalk@mimuw.edu.pl`. GitHub username: [Awerin](https://github.com/Awerin). - + **Additional duties:** Michał will be accepting EWP specifications on behalf of Poland, but he will also be implementing a set of common libraries which other partners may be wanting to use. From 9764607e06cb986c8924c9a568e25ec39c3de353 Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Mon, 18 Jan 2016 22:58:44 +0100 Subject: [PATCH 12/14] Spelling Fixes issue #1. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index db1be01..0ae1e41 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ We chose to use Git and GitHub as the primary tool for working and hosting * GitHub features include an integrated code review tools, issue trackers, change notifications, automated build tools - and many other features. We - are aware that our most of the repositories will be hosting documentation + are aware that most of our repositories will be hosting documentation only, but we do find all these tools useful even in documentation-only projects. From 7f12eced65a8bdbc91aaee1c8627ecddd66cff77 Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Tue, 26 Jan 2016 10:22:25 +0100 Subject: [PATCH 13/14] Release rules, data and documentation formats --- README.md | 93 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 49 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 0ae1e41..3869542 100644 --- a/README.md +++ b/README.md @@ -183,32 +183,35 @@ change logs). ### Preferred Data Formats -*WRTODO: The preferred data format is yet to be decided upon.* +We have decided for XML to be the **primary** data exchange format in our APIs. - * XML? (our current pick) - * JSON? +It is possible for some APIs to use some other data formats (especially if the +format is a well-established one, for exchanging some particular type of data), +but whenever in doubt, we SHOULD choose a format based on XML (and validatable +by XML Schema). ### Preferred Documentation Format -*WRTODO: The preferred documentation format is yet to be decided upon.* +We have decided for Markdown and XML Schema to be our **primary** documentation +formats. - * Markdown? (our current pick) - * reStructuredText? - * JSON Schema? - * XML Schema? (our current pick) + * **Markdown** - because it is very easy to understand even when displayed + *raw*. This makes it a very good language to be reviewed in Git diffs. -Regardless of what we choose, we do have some requirements on the documentation -itself: + * **XML Schema** - because it is a well-established documentation format for + XML, and makes it easier for developers to confirm that their documents meet + the requirements. - * We require all API specifications to be **explicit and strict** (with lots - of "MUSTs" and "MUST NOTs" and detailed explanations for all the - enumerations used). If any part of the specifications turns out to be vague, - then a new version of such specification SHOULD be released, fixing the - vague part. - * Let's try to avoid changing the format of the specification after it has - been first released (as this would "break the diffs"). +### Preferred Documentation Style + +We require all API specifications to be **explicit and strict** - with lots +of "MUSTs" and "MUST NOTs" (as defined in [RFC 2119] +(https://www.ietf.org/rfc/rfc2119.txt)) and detailed explanations for all +the enumerations used). If any part of the specifications turns out to be +vague, then a new version of such specification SHOULD be released, fixing the +vague part. ### Use permalinks! @@ -270,7 +273,7 @@ GitHub organization. -Rules for Submitting API Change Proposals +Rules for Accepting API Change Proposals ----------------------------------------- ### How to propose a change to a document? @@ -292,29 +295,39 @@ Rules for Submitting API Change Proposals ### How to get my draft (or change proposal) released? -You CANNOT assume that all partners are watching all of the issues. You MUST -contact all the partners (see the *EWP Partners and Developers* section below) -and attempt to get their approval before you can deem your proposal as ready to -be released. +These rules apply to developers with write-permissions to official EWP +repositories. Developers MUST follow these rules whenever they want to release +a new version of a document. + + * All [change proposals][statuses] SHOULD be accompanied by a [pull request] + (https://help.github.com/articles/using-pull-requests/). Partners MUST be + able to review a diff of all changes, and be allowed to comment on this diff + somewhere. - * Only trivial changes of already implemented APIs may be merged without - asking for the approval of the other partners. + * This is also true when releasing [drafts][statuses] - e.g. if the draft is + present in the `master` branch, then you should issue yourself a pull + request to the `stable-*` branch. - * [Breaking changes](https://en.wiktionary.org/wiki/breaking_change) to - existing [releases][statuses] MUST be explicitly accepted by all - the partners. + * Only trivial changes of already implemented APIs may be released without + previously asking for the review of the other partners. - * Non-breaking changes to existing releases MAY be deemed as implicitly - accepted no sooner than **1 week** after they have been proposed (and no - "veto" was received), but this time span SHOULD be extended if there is - reason to suspect some partners may don't like the change. + * You CANNOT assume that all partners are watching all GitHub issues and/or + pull requests. Whenever you mean to contact the partners, you MUST do so + either directly, or via the technical@erasmuswithoutpaper.eu mailing list. - * Upgrading [draft][statuses] to a [release candidate][statuses] SHOULD be - explicitly accepted by all the partners. + * Whenever you contact the partners and ask for their review, you MAY give + them a **deadline** for such review. After such deadline is reached, it MAY + be assumed that all the partners who did not respond gave you their + approval. - * All [change proposals][statuses] SHOULD be accompanied by a pull request. - Partners MUST be able to review a diff of all changes, and be allowed to - comment on this diff somewhere. + * Deadlines should vary on the nature of the change. E.g. A one-week + deadline might be enough for non-breaking changes, but + [breaking changes](https://en.wiktionary.org/wiki/breaking_change) to + [already released][statuses] documents may need a longer deadline. + + * If there is a strong reason to suspect that some partners may don't like + the change (e.g. you know the implementation has already started), you + SHOULD attempt to contact them directly and get their *explicit* approval. EWP Partners and Developers @@ -353,14 +366,6 @@ We intend to keep this list here, as part of this document. *(WRTODO: full list of the partners)* -Relevant external documents ---------------------------- - - * [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) - strict definitions of - keywords such as "MUST" and "SHOULD" (which we will use throughout all the - documents). - - [develhub]: http://developers.erasmuswithoutpaper.eu/ [statuses]: https://github.com/erasmus-without-paper/ewp-specs-management/blob/master/README.md#statuses [backward-compatibility-rules]: https://github.com/erasmus-without-paper/ewp-specs-architecture/blob/master/README.md#backward-compatibility-rules From 809c623aa11981362eca61e90c75e8e5fc161590 Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Fri, 29 Jan 2016 09:58:50 +0100 Subject: [PATCH 14/14] Bring JSON back, remove the list of partners We might still use JSON in some API, so it wouldn't be appropriate to release a document stating that we will use XML Schema only. The list partner developers is not complete it would be better to remove it for now. Maybe it will be brought back later. --- README.md | 58 ++++++++++++++----------------------------------------- 1 file changed, 14 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 3869542..0a50860 100644 --- a/README.md +++ b/README.md @@ -183,25 +183,31 @@ change logs). ### Preferred Data Formats -We have decided for XML to be the **primary** data exchange format in our APIs. +We are inclined to use XML as our primary data exchange format. We might be +persuaded towards JSON however. Further inquiry will be conducted and decisions +will be released in future versions of this document. -It is possible for some APIs to use some other data formats (especially if the -format is a well-established one, for exchanging some particular type of data), -but whenever in doubt, we SHOULD choose a format based on XML (and validatable -by XML Schema). +Regardless of what we choose, it is possible for some APIs to use some other +data formats than the "primary" ones (especially if the format is a +well-established one, for exchanging some particular type of data). ### Preferred Documentation Format -We have decided for Markdown and XML Schema to be our **primary** documentation -formats. +We have decided to use Markdown for text documentation. We will also use schema +languages (such as XML Schema or JSON Schema) for describing data formats in +detail. * **Markdown** - because it is very easy to understand even when displayed *raw*. This makes it a very good language to be reviewed in Git diffs. * **XML Schema** - because it is a well-established documentation format for XML, and makes it easier for developers to confirm that their documents meet - the requirements. + the requirements. Schema validators are already built into many programming + languages. + + * **JSON Schema** - not (yet?) so popular, but there are multiple validators + on the web, available for many programming languages. ### Preferred Documentation Style @@ -330,42 +336,6 @@ a new version of a document. SHOULD attempt to contact them directly and get their *explicit* approval. -EWP Partners and Developers ---------------------------- - -While the EWP Project lasts, new specifications will be drafted and released. -This requires all the partners to agree on the contents of these -specifications. Every partner will provide its representatives - developers -which will accept specifications in the name of the partner. - -Some other developers may have some special or additional duties (which should -also be a part of the common knowledge). - -We intend to keep this list here, as part of this document. - - -### Poland - - * Wojciech Rygielski - `rygielski@mimuw.edu.pl`. GitHub username: - [wrygiel](https://github.com/wrygiel) - - **Additional duties:** I am in charge of the [developer's pages][develhub] - and keeping the EWP specifications clean, up-to-date and (if possible) - backward-compatible. I will also be keeping track of which partners have - accepted which documents. In general, I won't be taking part in implementing - the Polish *EWP Host*, but I will probably be implementing the EWP Registry - Service. - - * Michał Kurzydłowski - `michalk@mimuw.edu.pl`. GitHub username: - [Awerin](https://github.com/Awerin). - - **Additional duties:** Michał will be accepting EWP specifications on behalf - of Poland, but he will also be implementing a set of common libraries which - other partners may be wanting to use. - -*(WRTODO: full list of the partners)* - - [develhub]: http://developers.erasmuswithoutpaper.eu/ [statuses]: https://github.com/erasmus-without-paper/ewp-specs-management/blob/master/README.md#statuses [backward-compatibility-rules]: https://github.com/erasmus-without-paper/ewp-specs-architecture/blob/master/README.md#backward-compatibility-rules