diff --git a/content/00.front-matter.md b/content/00.front-matter.md index 2c18248..f2a58b0 100644 --- a/content/00.front-matter.md +++ b/content/00.front-matter.md @@ -5,6 +5,7 @@ ##}
+![](images/logo-SYNERGY.png){height="50px"}     ![](images/logo-DEEP.png){height="50px"}     ![](images/logo-INDIGO.png){height="50px"}     ![](images/logo-XDC.png){height="50px"} diff --git a/content/01.abstract.md b/content/01.abstract.md index 22703cd..3c5e0c0 100644 --- a/content/01.abstract.md +++ b/content/01.abstract.md @@ -1,4 +1,5 @@ ## Abstract {.page_break_before} + The purpose of this document is to define a set of quality standards, procedures and best practices to conform a Software Quality Assurance plan to serve as a reference within the European research ecosystem related projects diff --git a/content/02.0.copyright-ack.md b/content/02.0.copyright-ack.md index 40f32b1..725aa34 100644 --- a/content/02.0.copyright-ack.md +++ b/content/02.0.copyright-ack.md @@ -1,12 +1,14 @@ ## Copyright Notice + Copyright © Members of the INDIGO-DataCloud, DEEP Hybrid-DataCloud and eXtreme DataCloud collaborations, 2015-2020. ## Acknowledgements -The INDIGO-DataCloud, DEEP-Hybrid-DataCloud and eXtreme-DataCloud -projects have received funding from the European Union’s Horizon 2020 -research and innovation programme under grant agreement number 653549, -777435 and 777367 respectively. + +The INDIGO-DataCloud, DEEP-Hybrid-DataCloud, eXtreme-DataCloud and +EOSC-Synergy projects have received funding from the European Union’s +Horizon 2020 research and innovation programme under grant agreement +number 653549, 777435, 777367 and 857647 respectively.

diff --git a/content/02.document-log.md b/content/02.document-log.md index 4ef8fc3..de1ee3e 100644 --- a/content/02.document-log.md +++ b/content/02.document-log.md @@ -1,5 +1,7 @@ ## Document Log + | Issue | Date | Comment | |----------|----------|----------| | v1.0 | 31/01/2018 | First draft version | | v2.0 | 05/02/2018 | Updated criteria | +| v3.0 | 20/12/2019 | Code management section, metadata for software | diff --git a/content/03.intro.md b/content/03.intro.md index df59e01..7520b24 100644 --- a/content/03.intro.md +++ b/content/03.intro.md @@ -1,10 +1,11 @@ ## Introduction and Purpose + This document has been tailored upon the recommendations and requirements found in the Initial Plan for Software Management and Pilot Services deliverable @url:https://owncloud.indigo-datacloud.eu/index.php/s/yDklCrWjKnjutVA, produced by the INDIGO-DataCloud project. These guidelines evolved throughout -the project’s lifetime and have been eventually extended in the -DEEP-Hybrid-DataCloud and eXtreme DataCloud subsequent projects. The result is +the project’s lifetime and are being extended in the +EOSC-Synergy, DEEP-Hybrid-DataCloud and eXtreme DataCloud subsequent projects. The result is a consolidated Software Quality Assurance (SQA) baseline criteria emanated from the European Open Science Cloud (EOSC), which aims to outline the SQA principles to be considered in the upcoming software development efforts within diff --git a/content/04.goals.md b/content/04.goals.md index 007e132..a90c2d9 100644 --- a/content/04.goals.md +++ b/content/04.goals.md @@ -1,4 +1,5 @@ ## Goals + 1. Set the base of minimum SQA criteria that a software developed within EOSC development project SHOULD fulfill. 2. Enhance the visibility, accessibility and distribution of the produced diff --git a/content/05.notational_conventions.md b/content/05.notational_conventions.md index 589105d..65b9c60 100644 --- a/content/05.notational_conventions.md +++ b/content/05.notational_conventions.md @@ -1,4 +1,5 @@ ## Notational Conventions + The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 @url:https://www.ietf.org/rfc/rfc2119.txt. diff --git a/content/06.quality_criteria.md b/content/06.quality_criteria.md index 3e34543..751097c 100644 --- a/content/06.quality_criteria.md +++ b/content/06.quality_criteria.md @@ -1,4 +1,5 @@ ## Quality Criteria + The following sections describe the quality conventions and best practices that apply to the development phase of a software component within the EOSC ecosystem. These guidelines ruled the software development process of the @@ -14,17 +15,19 @@ Consequently, software components are more eligible for being deployed in production infrastructures, reducing the likelihood of service disruption. ### Code Accessibility + 1. Following the open-source model, the source code being produced MUST be open and publicly available to promote the adoption and augment the visibility of the software developments. 2. Source code MUST use a Version Control System (VCS). i. It is RECOMMENDED that all software components delivered by the same - project agree on a common VCS. + project agree on a common VCS. 3. Source code produced within the scope of a broader development project SHOULD reside in a common organization of a version control repository hosting service. ### Licensing + 1. As open-source software, source code MUST adhere to an open-source license to be freely used, modified and distributed by others. i. Non-licensed software is exclusive copyright by default. @@ -35,6 +38,7 @@ to be freely used, modified and distributed by others. all the source code repositories related to the software component. ### Code Workflow + A change-based approach is accomplished with a branching model. 1. The main branch in the source code repository MUST maintain a working state @@ -57,15 +61,39 @@ A change-based approach is accomplished with a branching model. 4. Semantic Versioning @url:https://semver.org specification is RECOMMENDED for tagging the production releases. +### Code Management +1. An issue tracking system facilitates structured software development. Leveraging + issues to track down both new enhancements and defects (bugs or documentation typos) + is RECOMMENDED. + i. In addition to monitoring the internal development, issues are the best means for + supporting users. External users SHOULD be able to create incidences based on the + operational performance of the software. + ii. The description of an issue SHOULD be concise and state clearly the problem. It is + RECOMMENDED to add any reference to the actual problem. In the case of bugs, the + issue SHOULD be accompanied by the relevant debug information. + * The usage of templates for the issue description is RECOMMENDED. +2. In social coding environments, pull requests represent the cornerstone of collaboration. + A pull request provides a place for review and discussion of the changes proposed to be + part of an existing version of the code. + i. Pull requests SHOULD be used for every change in the codebase. + ii. A software project SHOULD be open to external collaboration through pull requests. + iii. A pull request description SHOULD be concise and state clearly its purpose (e.g. if + it is fixing an observed bug or adding a new feature) + * The usage of templates for the pull request's description is RECOMMENDED. + iv. It is RECOMMENDED to use pull requests to address open issues. The pull request + description SHOULD make reference to the identifiers of the issues it is fixing + (to eventually close them, either manually or automatically). + ### Code Style + Code style requirements pursue the correct maintenance of the source code by the common agreement of a series of style conventions. These vary based on the programming language being used. -1. Each individual software product MUST comply with a de-facto code style - standard for althe programming languages used in the codebase. - i. Compliance with multiple standards MAY exist. -2. Custom code style guidelines MUST be avoided, only considered in the +1. Each individual software product MUST comply with community-driven or de-facto + code style standards for the programming languages being used. + i. Compliance with multiple complementary standards MAY exist. +2. Custom code style guidelines SHOULD be avoided, only considered in the hypothetical event of programming languages without existing community style standards. i. Custom styles MUST be documented by defining each convention and its @@ -78,7 +106,18 @@ programming language being used. 4. Code style compliance testing MUST be automated and MUST be triggered for each candidate change in the source code. +### Code metadata + +Metadata for the software component provides a way to achieve its full identification, +thus making software citation viable [@url:http://dx.doi.org/10.7717/peerj-cs.86]. +It allows the assignement of a Digital Object Identifier (DOI) and is key +towards preservation, discovery, reuse, and attribution of the software component. + +A metadata file SHOULD exist along side the code, under its VCS. +The metadata file SHOULD be updated when needed, as is the case of a new version. + ### Unit Testing + Unit testing evaluates all the possible flows in the internal design of the code, so that its behaviour becomes apparent. It is a key type of testing for early detection of failures in the development cycle. @@ -97,6 +136,7 @@ early detection of failures in the development cycle. RECOMMENDED to mimic a simplistic behaviour of objects and procedures. ### Functional Testing + Functional testing involves the verification of the software component’s identified functionality, based on requested requirements and agreed design specifications. This type of software testing focus on the evaluation of the @@ -120,6 +160,7 @@ design analysis or side-effects to external systems. testing. ### Integration Testing + Integration testing refers to the evaluation of the interactions among coupled software components or parts of a system that cooperate to achieve a given functionality. @@ -129,12 +170,13 @@ functionality. 2. Integration testing MAY be complemented with Acceptance and Scalability testing. 3. Integration testing MAY NOT be suitable for automated testing. -4. On lack of automation, pilot service infrastructures or local testbeds MAY - be used. +4. Ad-hoc pilot service infrastructures and/or local testbeds MAY be used to + cope with the integration testing requirements. 5. Integration testing MAY NOT be viable to be checked on change basis, as it is likely to involve complex scenarios. ### Documentation + 1. Documentation MUST be treated as code. i. Version controlled, it MAY reside in the same repository where the source code lies. @@ -187,6 +229,7 @@ functionality. 7. Documentation MUST be checked on change basis. ### Security + 1. Secure coding practices SHALL be applied into all the stages of a software component development lifecycle. i. Compliance with Open Web Application Security Project (OWASP) secure @@ -215,6 +258,7 @@ functionality. requirements set at the operational level. ### Code Review + Code review implies the informal, non-automated, peer, human-based revision of any change in the source code. It appears as the last step in the change management pipeline, once the candidate change has successfully passed over the @@ -234,8 +278,8 @@ required set of change-based tests. deadlines. 2. Code reviews MUST be open and collaborative, allowing external expert revisions. -3. Code reviews SHOULD be lightweight and informal, meaning that some of the - areas the reviewers MAY focus are: +3. Code reviews SHOULD be concise and use neutral language. The areas where the + reviewers MAY focus are: i. Message description: commit message is clear, self-explanatory and describes precisely the objectives being addressed. ii. Goal or scope: change is needed and/or addresses/fixes the whole set of @@ -252,6 +296,7 @@ required set of change-based tests. the changes. ### Automated Deployment + Production-ready code SHALL be deployed as a workable system with the minimal user or system administrator interaction leveraging software configuration management (SCM) tools. diff --git a/content/07.glossary.md b/content/07.glossary.md index d99587f..a23a4a9 100644 --- a/content/07.glossary.md +++ b/content/07.glossary.md @@ -1,4 +1,5 @@ ## Glossary + __API__ : Application Programming Interface diff --git a/content/images/logo-SYNERGY.png b/content/images/logo-SYNERGY.png new file mode 100644 index 0000000..11a6fdd Binary files /dev/null and b/content/images/logo-SYNERGY.png differ diff --git a/content/manual-references.json b/content/manual-references.json index 3acf58e..976a889 100644 --- a/content/manual-references.json +++ b/content/manual-references.json @@ -127,5 +127,59 @@ "literal": "The OWASP Foundation" } ] +}, +{ + "type":"article-journal", + "publisher":"PeerJ", + "DOI":"10.7717/peerj-cs.86", + "page":"e86", + "source":"Crossref", + "title":"Software citation principles", + "volume":2, + "author":[ + { + "ORCID":"http://orcid.org/0000-0002-3957-2474", + "authenticated-orcid":true, + "given":"Arfon M.", + "family":"Smith", + "sequence":"first", + "affiliation":[ + { + "name":"GitHub, Inc., San Francisco, California, United States" + } + ] + }, + { + "ORCID":"http://orcid.org/0000-0001-5934-7525", + "authenticated-orcid":true, + "given":"Daniel S.", + "family":"Katz", + "sequence":"additional", + "affiliation":[ + { + "name":"National Center for Supercomputing Applications & Electrical and Computer Engineering Department & School of Information Sciences, University of Illinois at Urbana-Champaign, Urbana, Illinois, United States" + } + ] + }, + { + "ORCID":"http://orcid.org/0000-0003-4425-7097", + "authenticated-orcid":true, + "given":"Kyle E.", + "family":"Niemeyer", + "sequence":"additional", + "affiliation":[ + { + "name":"School of Mechanical, Industrial, and Manufacturing Engineering, Oregon State University, Corvallis, Oregon, United States" + } + ] + } + ], + "container-title":"PeerJ Computer Science", + "language":"en", + "issued":{"date-parts":[[2016,9,19]]}, + "standard_citation":"http://dx.doi.org/10.7717/peerj-cs.86", + "URL":"http://dx.doi.org/10.7717/peerj-cs.86", + "ISSN":"2376-5992", + "id":"temp_id_7660989779236345" } ]