The AARC project, in collaboration with partners such as the Infrastructure, AEGIS, IGTF, REFEDS, FIM4R and WISE, periodically releases guidance to the community on how to best support authentication and authorisation for research and collaboration. This guidance takes the form of Guideline Documents that are public and have persistently identifiable (and can be so referenced). This pages describes the document process, assignment of identifiers, maintenance of document status information, and publication.
Overview of Documents
Documents are numbered sequentially, and take an identifier of the form "AARC-Gxxx", where xxx is a three-digit monotonically increasing number. Numbers are assigned
- whenever a concept is developed of proposed that could merit a guideline document even if it is not yet certain such a document will ever be published.
- whenever a document jointly developed with others merit import of its contents in the AARC guidelines series
- the numbering scheme MAY (and will) have holes in it. This is no big deal: it is similar with CVE numbers, and it allows forward referencing
An AARC Guidelines identifier MUST be assigned to all version of the BPA, to all technical recommendations that pertain to the BPA, to all policy guidance that pertains to Infrastructure proxies and consortia of service providers or IdPs, and for specifications that should be adopted or implemented by the AARC peer organisations. It MUST be assigned to all document that will be published, and MAY be assigned to project deliverables and milestone documents that have value as guidance.
| Assign numbers and review/edit status here:https://docs.google.com/spreadsheets/d/1rvxtSyZBucT0xUTcajWa4YOJ-A8_v4KKgun0aJR1AF4 |
|---|
Document numbers can be assigned by the PMT members. Everyone can comment and suggest improvements (e.g. to the abstract or status).
A workable document template for those using MS Word is also attached to this page (it actually uses document properties correctly so can be indexed). For non-project documents, drop the "Contractual Date" (up to ..."Lead Partner") bit from it, since for guideline documents it does not make sense. Do keep the copyright and EC funding tag line!
Status information and transitions
Each document has a status value assigned in the table
| Status | Description | Next state(s) |
|---|---|---|
| Concept | Somebody thought that this topic merited guidance | In Progress |
| Abandoned | This idea will not be pursued ever again, or only in a different context | - |
| In Progress | Somebody actually started work on the idea. This must be reflected in a Wiki page that contains at least an abstract (few lines) and a link to discussion meetings or a draft document | Consultation |
| On Hold | Work has been suspended under the assumption that it will be resumed later (e.g waiting on community feed-back or clarification of use cases) | Abandoned In Progress |
| Consultation | The guidance has been developed sufficiently to expose a draft to the interested communities (REFEDS, AppInt, IGTF, WISE, or the WP mailing list | In Progress |
| Final Call | Document has been sent to all of AARC and to all relevant stakeholders for final comment | In Progress |
| Final | This guidance is now official AARC guidance and will be published in the 'main' lists of guidance documents on https://aarc-project.eu/guidelines/. This state must be reflected in the public page of the guideline under https://aarc-project.eu/guidelines/aarc-gXXX/ under "Status". A DOI must now be assigned if it has not been assigned already | - Endorsed Superseded |
| Endorsed by ... | This guidance has been endorsed by a target audience of AARC (AEGIS) or an external peer body (REFEDS, IGTF, &c). It gives the document more status, and this must be reflected on the public guidlines pages. E.g. "Status: Endorsed by AEGIS", or "Status: Endorsed by REFEDS and AEGIS". | - |
It is RECOMMENDED that each document has a Guarding Angel that shepherds the document through the transitioning process. The GA MAY be the Editor.
Publication
- All Guidelines will be published on the aarc-project.eu public web page under https://aarc-project.eu/guidelines/
- The Guidelines web page will have section according to the (approx) target audience:
- Architecture (technical) Guidance
- Policy Guidance
- Targeted Guidance (directed towards specific communities or infrastructures, e.g. for the LSAAI proxy)
- Upcoming Guidance (future work, any doc that is in the In Progress/Consultation/Final Call state, and relevant docs that are in the Concept stage
- A published Guidelines document should have the document number embedded in it. This may be post-edited in the PDF as a marker
- Each document MUST have an abstract, and the abstract text MUST come from the Document Sheet above
- A DOI should be assigned to each document that has value outside the project, directly after the Final Call state and before becoming Final. The DOI, to be obtained from Zenodo unless otherwise given or already assigned, should be embedded in the document. Note that you can RESERVE a DOI on Zenodo before publication by providing basic meta-data: http://help.zenodo.org/. A DOI assignment may be deferred in case the usability status of the document outside the project is not known at time of publication. It may be assigned and embedded later without a status change to the document.