Merge pull request #37 from indigo-dc/release/v3.0

Release/v3.0

content/00.front-matter.md

@@ -5,6 +5,7 @@
 ##}
 
 <br>
+![](images/logo-SYNERGY.png){height="50px"}&nbsp;&nbsp;&nbsp;&nbsp;
 ![](images/logo-DEEP.png){height="50px"}&nbsp;&nbsp;&nbsp;&nbsp;
 ![](images/logo-INDIGO.png){height="50px"}&nbsp;&nbsp;&nbsp;&nbsp;
 ![](images/logo-XDC.png){height="50px"}

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

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.
 <p align="center">
   <img src="https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcT1WF4g5KH3PnQE_Ve10QFRS-gZ0NpCQ7Qr-_km1RqnOCEF1fQt">
 </p>

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 |

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

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

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.

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.

content/07.glossary.md

@@ -1,4 +1,5 @@
 ## Glossary
+
 __API__
 : Application Programming Interface
 

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"
 }
 ]