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 are persistently identifiable (and can be so referenced). This pages describes the document process, assignment of identifiers, maintenance of document status information, and publication.
AARC Guidelines can apply to any topic that helps further FIM for research and collaboration: composition of components into an architecture, lists of tools that fulfill a particular role in an operational deployment, policy frameworks, specific instructions on how to configure your proxy to comply with the data protection code of conduct, and even 'one statement' policies where the guideline is just one statement (like "An IdP-SP-proxy must assert the value "coffee" in the voPersonFavouriteBeverage attribute towards all connected relying parties and service providers"). Guidelines help communities and infrastructures, and the people implementing and operating an AAI for research and collaboration in running it more effectively and in an interoperable way.
Overview of Documents
Documents are numbered sequentially, and take an identifier of the form "AARC-Gxxx", or "AARC-Ixxx" (for informational white papers), 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, and where AARC has significantly contributed to this outcome (for example: Sirtfi clearly has a strong AARC contribution to it so can be in the series, but REFEDS R&S does not, so should NOT be included, even though we heavily use it).
- 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 versions 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.
| Number assignment, review, and edit status :https://docs.google.com/spreadsheets/d/1rvxtSyZBucT0xUTcajWa4YOJ-A8_v4KKgun0aJR1AF4 |
|---|
Document numbers can be assigned by the AARC management team members.
A 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. A DOI may be reserved at this stage if the document has external value. | 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 the document has external value, and 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 IGTF 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.