From 571e5d5d6eed1a714344d4931172125541d4a633 Mon Sep 17 00:00:00 2001 From: Tierney Cyren Date: Thu, 31 Jan 2019 17:56:59 -0500 Subject: [PATCH 1/4] Create ci-cd-guidelines.md An initial proposal for `ci-cd-automation-guidelines.md`, which outlines bare minimum set of requirements around CI/CD templates. --- docs/drafts/ci-cd-guidelines.md | 38 +++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/drafts/ci-cd-guidelines.md diff --git a/docs/drafts/ci-cd-guidelines.md b/docs/drafts/ci-cd-guidelines.md new file mode 100644 index 00000000..bd09eb95 --- /dev/null +++ b/docs/drafts/ci-cd-guidelines.md @@ -0,0 +1,38 @@ +## What? +Guidelines for CI/CD automation templates. + +## Why? +Provide a baseline, common set of CI/CD infrastructure that can be relied upon regardless of what CI/CD providers are used by a project. + +## How? +These guidelines are intended to be just that – guidelines. We will also include templates for common CI/CD providers and accept contributions of templates that implement these guidelines from the community. + +It's worth noting that projects **do not** need to use one of the provided templates, but **do** need to ensure that their CI/CD setup enables them to follow the required guidelines at the very minimum. Projects are by no means restricted to the required guidelines – more complex and dynamic configurations are more than welcome. + +## CI/CD Templates Should Include: + +- Tests + - Criteria (**Required**): + - `npm test` + - This can be any testing framework exposed via `npm test`. + - Many CI/CD systems run this implicitly for JavaScript projects. You do not need to explicitly define `npm test` in these cases. + - Criteria (**Optional**): + - code coverage + - failure if code coverage is below a well-documented threshold +- Caching + - Criteria (**Required**): + - At a minimum, cache `node_modules` (or equivalent) for your project +- Operating System Versions + - Criteria (**Required**): + - Windows + - macOS + - Linux + - At least one current and one LTS release + - Ubuntu is suggested but not required +- Node.js Versions + - Criteria (**Required**): + - nodejs@current + - nodejs@lts + - This includes all active and maintenance versions + - Criteria (**Optional**): + - nodejs@nightly From 8ffe1d3fc9e6ea31323389f1fd602e47c512509f Mon Sep 17 00:00:00 2001 From: Tierney Cyren Date: Fri, 15 Mar 2019 16:10:46 -0700 Subject: [PATCH 2/4] Updates addressing requested changes --- docs/drafts/ci-cd-guidelines.md | 33 +++++++++++++++++++++------------ 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/docs/drafts/ci-cd-guidelines.md b/docs/drafts/ci-cd-guidelines.md index bd09eb95..df2727ee 100644 --- a/docs/drafts/ci-cd-guidelines.md +++ b/docs/drafts/ci-cd-guidelines.md @@ -1,5 +1,7 @@ ## What? -Guidelines for CI/CD automation templates. +Guidelines for CI/CD automation templates to be shipped by the package-maintenance team. + +> **Note:** This set of guidelines _is not_ about telling projects what they can and cannot do. Instead, it's a framework for those who are interested in building out bare-minium CI/CD templates for projects in the JavaScript ecosystem to use. ## Why? Provide a baseline, common set of CI/CD infrastructure that can be relied upon regardless of what CI/CD providers are used by a project. @@ -9,30 +11,37 @@ These guidelines are intended to be just that – guidelines. We will also inclu It's worth noting that projects **do not** need to use one of the provided templates, but **do** need to ensure that their CI/CD setup enables them to follow the required guidelines at the very minimum. Projects are by no means restricted to the required guidelines – more complex and dynamic configurations are more than welcome. -## CI/CD Templates Should Include: +## Definitions +Definitions for the various terms used in the guidelines: + +### Required +To say a CI/CD template follows the "tests" guidelines documented here, it would need to meet all of the **required** marks. The same approach applies to for all other guidelines. + +### Optional +**Optional** guidelines are, as the name indicates, optional for templates to include. They're _nice to have_ but by no means required. +## CI/CD Guidelines: - Tests - - Criteria (**Required**): + - **Required**: - `npm test` - This can be any testing framework exposed via `npm test`. - Many CI/CD systems run this implicitly for JavaScript projects. You do not need to explicitly define `npm test` in these cases. - - Criteria (**Optional**): + - `npm ls` + - If `npm ls` exits with a `0` exit code, your build should pass + - If `npm ls` exits with a non-`0` exit code, your dependnecy graph is invalid and should fail the run + - **Optional**: - code coverage - failure if code coverage is below a well-documented threshold -- Caching - - Criteria (**Required**): - - At a minimum, cache `node_modules` (or equivalent) for your project - Operating System Versions - - Criteria (**Required**): + - **Required**: - Windows - macOS - Linux - - At least one current and one LTS release - - Ubuntu is suggested but not required + - All active LTS releases of Ubuntu or your CI provider's default Linux OS - Node.js Versions - - Criteria (**Required**): + - **Required**: - nodejs@current - nodejs@lts - This includes all active and maintenance versions - - Criteria (**Optional**): + - **Optional**: - nodejs@nightly From 8e4483ad6cc638d6af20472ae6af110246946320 Mon Sep 17 00:00:00 2001 From: Tierney Cyren Date: Fri, 15 Mar 2019 16:11:39 -0700 Subject: [PATCH 3/4] Formatting fixes --- docs/drafts/ci-cd-guidelines.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/drafts/ci-cd-guidelines.md b/docs/drafts/ci-cd-guidelines.md index df2727ee..5ae7f118 100644 --- a/docs/drafts/ci-cd-guidelines.md +++ b/docs/drafts/ci-cd-guidelines.md @@ -1,26 +1,33 @@ -## What? +## What + Guidelines for CI/CD automation templates to be shipped by the package-maintenance team. > **Note:** This set of guidelines _is not_ about telling projects what they can and cannot do. Instead, it's a framework for those who are interested in building out bare-minium CI/CD templates for projects in the JavaScript ecosystem to use. -## Why? +## Why + Provide a baseline, common set of CI/CD infrastructure that can be relied upon regardless of what CI/CD providers are used by a project. -## How? +## How + These guidelines are intended to be just that – guidelines. We will also include templates for common CI/CD providers and accept contributions of templates that implement these guidelines from the community. It's worth noting that projects **do not** need to use one of the provided templates, but **do** need to ensure that their CI/CD setup enables them to follow the required guidelines at the very minimum. Projects are by no means restricted to the required guidelines – more complex and dynamic configurations are more than welcome. ## Definitions + Definitions for the various terms used in the guidelines: ### Required + To say a CI/CD template follows the "tests" guidelines documented here, it would need to meet all of the **required** marks. The same approach applies to for all other guidelines. ### Optional + **Optional** guidelines are, as the name indicates, optional for templates to include. They're _nice to have_ but by no means required. -## CI/CD Guidelines: +## CI/CD Guidelines + - Tests - **Required**: - `npm test` From 0be3dc7aab16639c6f145e08825d5e822de58da5 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Tue, 11 Jun 2019 23:39:14 +0200 Subject: [PATCH 4/4] Update docs/drafts/ci-cd-guidelines.md Co-Authored-By: Jordan Harband --- docs/drafts/ci-cd-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/drafts/ci-cd-guidelines.md b/docs/drafts/ci-cd-guidelines.md index 5ae7f118..105cc1fd 100644 --- a/docs/drafts/ci-cd-guidelines.md +++ b/docs/drafts/ci-cd-guidelines.md @@ -35,7 +35,7 @@ To say a CI/CD template follows the "tests" guidelines documented here, it would - Many CI/CD systems run this implicitly for JavaScript projects. You do not need to explicitly define `npm test` in these cases. - `npm ls` - If `npm ls` exits with a `0` exit code, your build should pass - - If `npm ls` exits with a non-`0` exit code, your dependnecy graph is invalid and should fail the run + - If `npm ls` exits with a non-`0` exit code, your dependency graph is invalid and should fail the run - **Optional**: - code coverage - failure if code coverage is below a well-documented threshold