From f1a17a3331761c9745988497d82d9b527ed0d139 Mon Sep 17 00:00:00 2001 From: Ethan Davis Date: Wed, 20 May 2020 00:54:48 -0600 Subject: [PATCH 1/6] Add Infrastructure Guide --- infrastructure-guide.md | 71 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 infrastructure-guide.md diff --git a/infrastructure-guide.md b/infrastructure-guide.md new file mode 100644 index 000000000..d87d4b58b --- /dev/null +++ b/infrastructure-guide.md @@ -0,0 +1,71 @@ +# Infrastructure Guide + +This guide serves as an advanced version of the contributing documentation +and contains the information on how we manage the infrastructure +behind the CF Website, Conventions document, CF Standard Names table, +and standardized region list. + +## CF Website + +The [CF Website](http://cfconventions.org) is served by GitHub Pages +from source documents (in Markdown mainly) on the `master` branch +of the [CF Website repo](https://github.com/cf-convention/cf-convention.github.io). +The CF Website pages are regenerated automatically by GitHub Pages +whenever a commit is made to the `master` branch. + +### PR Testing for the CF Website + +PRs to the CF website repo are built/tested by GitHub Actions +using Jekyll with the 'github-pages' plugin. +The resulting website content is available as an artifact +from the CF Website repo's GitHub Actions [page](https://github.com/cf-convention/cf-convention.github.io/actions) +for the build of that PR. + +Configuration files are: +- [`check_jekyll_build.yml`](https://github.com/cf-convention/cf-convention.github.io/blob/master/.github/workflows/check_jekyll_build.yml) +- [`Gemfile`](https://github.com/cf-convention/cf-convention.github.io/blob/master/Gemfile) +- [`_config.yml`](https://github.com/cf-convention/cf-convention.github.io/blob/master/_config.yml) + +## CF Conventions Document +The CF Conventions Document is built from source documents (in AsciiDoc) +on the `master` branch of the [CF Conventions repo](https://github.com/cf-convention/cf-conventions). + +For each commit to the `master` branch of the CF Conventinos repo, +[Travis](https://travis-ci.org) builds the CF Conventions document(s) +using [Asciidoctor](https://asciidoctor.org/). +The resulting HTML page and PDF document are pushed to the `gh-pages` branch +and are served by GitHub Pages. +They are available at http://cfconventions.org/cf-conventions + +### Release Versions +??? Also done with Travis? + +Resulting HTML page and PDF document are pushed to the CF Website Repo +at `/Data/cf-conventions/cf-convention-` +from where they are published to the website +and available at +http://cfconventions.org/Data/cf-conventions/cf-conventions-/cf-conventions.[html|pdf] + +GitHub Releases are made ... +?? Should HTML and PDF output be included as assets in GitHub release? + +### PR Testing for the CF Conventions Document +PRs to the CF Convention repo are built/tested by GitHub Actions +using Asciidoctor. The resulting HTML page and PDF document are available +as artifacts in each build on the CF Conventions repo GitHub Actions [page](https://github.com/cf-convention/cf-conventions/actions) + +The configuration file for this GitHub Action is: +- [`check_adoc_build.yml`](https://github.com/cf-convention/cf-conventions/blob/master/.github/workflows/check_adoc_build.yml) + +## CF Standard Names Table +New CF Standard Names are discussed and proposed in issues on the [CF Discussion repo](https://github.com/cf-convention/discuss). +Proposed CF Standard Names are tracked in the [CEDA CF Standard Name Tracker](http://cfeditor.ceda.ac.uk/proposals/1). + +New versions of the CF Standard Name table are released ?monthly or quarterly? +with any newly accepted standard names. +The new XML file and XSLT-generated HTML file are pushed to the CF Website repo +in `Data/cf-standard-name//[build|src]`. + +## CF Standardized Region List + +?? \ No newline at end of file From e75818f8f5512682f5525e43a99aedd5c1c8eb1f Mon Sep 17 00:00:00 2001 From: Daniel Lee Date: Wed, 20 May 2020 09:48:12 +0200 Subject: [PATCH 2/6] Copyedit --- infrastructure-guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/infrastructure-guide.md b/infrastructure-guide.md index d87d4b58b..2fe03be09 100644 --- a/infrastructure-guide.md +++ b/infrastructure-guide.md @@ -30,7 +30,7 @@ Configuration files are: The CF Conventions Document is built from source documents (in AsciiDoc) on the `master` branch of the [CF Conventions repo](https://github.com/cf-convention/cf-conventions). -For each commit to the `master` branch of the CF Conventinos repo, +For each commit to the `master` branch of the CF Conventions repo, [Travis](https://travis-ci.org) builds the CF Conventions document(s) using [Asciidoctor](https://asciidoctor.org/). The resulting HTML page and PDF document are pushed to the `gh-pages` branch @@ -52,7 +52,7 @@ GitHub Releases are made ... ### PR Testing for the CF Conventions Document PRs to the CF Convention repo are built/tested by GitHub Actions using Asciidoctor. The resulting HTML page and PDF document are available -as artifacts in each build on the CF Conventions repo GitHub Actions [page](https://github.com/cf-convention/cf-conventions/actions) +as artifacts in each build on the CF Conventions repo GitHub Actions [page](https://github.com/cf-convention/cf-conventions/actions). The configuration file for this GitHub Action is: - [`check_adoc_build.yml`](https://github.com/cf-convention/cf-conventions/blob/master/.github/workflows/check_adoc_build.yml) @@ -68,4 +68,4 @@ in `Data/cf-standard-name//[build|src]`. ## CF Standardized Region List -?? \ No newline at end of file +?? From a4b63ad20cf997749f92579fad80f76193ef1410 Mon Sep 17 00:00:00 2001 From: Ethan Davis Date: Wed, 3 Jun 2020 23:15:09 -0600 Subject: [PATCH 3/6] Add section on CF Standard Names to infrastructure guide. --- infrastructure-guide.md | 55 +++++++++++++++++++++++++++++++++-------- 1 file changed, 45 insertions(+), 10 deletions(-) diff --git a/infrastructure-guide.md b/infrastructure-guide.md index 2fe03be09..baa006b93 100644 --- a/infrastructure-guide.md +++ b/infrastructure-guide.md @@ -30,15 +30,17 @@ Configuration files are: The CF Conventions Document is built from source documents (in AsciiDoc) on the `master` branch of the [CF Conventions repo](https://github.com/cf-convention/cf-conventions). +### Draft Version - Including all Accepted Proposals For each commit to the `master` branch of the CF Conventions repo, [Travis](https://travis-ci.org) builds the CF Conventions document(s) using [Asciidoctor](https://asciidoctor.org/). The resulting HTML page and PDF document are pushed to the `gh-pages` branch -and are served by GitHub Pages. -They are available at http://cfconventions.org/cf-conventions +and are served by GitHub Pages at http://cfconventions.org/cf-conventions. +As only accepted proposals and fixes are pushed to master, the resulting documents +are the draft version for the next release. ### Release Versions -??? Also done with Travis? +??? Also done with Travis? Need to confirm this. Resulting HTML page and PDF document are pushed to the CF Website Repo at `/Data/cf-conventions/cf-convention-` @@ -58,14 +60,47 @@ The configuration file for this GitHub Action is: - [`check_adoc_build.yml`](https://github.com/cf-convention/cf-conventions/blob/master/.github/workflows/check_adoc_build.yml) ## CF Standard Names Table -New CF Standard Names are discussed and proposed in issues on the [CF Discussion repo](https://github.com/cf-convention/discuss). -Proposed CF Standard Names are tracked in the [CEDA CF Standard Name Tracker](http://cfeditor.ceda.ac.uk/proposals/1). - -New versions of the CF Standard Name table are released ?monthly or quarterly? -with any newly accepted standard names. -The new XML file and XSLT-generated HTML file are pushed to the CF Website repo -in `Data/cf-standard-name//[build|src]`. +New CF Standard Names are proposed and discussed in issues on the +[CF Discussion repo][cf-discuss]. +Discussion of current and past proposed CF Standard Names, +including if and when they are accepted and ready for publication, +are tracked in the [CEDA CF Vocabulary Editor](http://cfeditor.ceda.ac.uk/proposals/1). + +When a new version of the CF Standard Names table is ready for release, +the CF Vocabulary Editor system is used to produces an XML file +that conforms to the schema used for the standard name table +(see Appendix B of the CF conventions). +An XSLT script is then used to render the XML into an HTML version of the Standard Names table. +Another process is run (see [below for details](#kwic-index)) to generate the HTML that is +the KWIC Index version of the Standard Names table. +The XML and HTML files are pushed to the [GitHub Website repo](https://github.com/cf-convention/cf-convention.github.io) +in `Data/cf-standard-name//[build|src]` so they are published (as described above) to the CF website. + +The CF Standard Names process is managed and led by @japamment and @feggleton. +For questions, please uses issues on the [CF Discussion repo][cf-discuss]. + +### Publishing to NERC Vocabulary Server +The [CF Standard Names vocabulary](http://vocab.nerc.ac.uk/collection/P07/current/) +on the [NERC Vocabulary Server (NVS)](http://vocab.nerc.ac.uk/) +is updated at the same time the CF Standard Names table is updated on the CF website. + +For each CF Standard Names table release, the CEDA Vocabulary Editor +also produces a tab separated file suitable for uploading to the NVS. +The NVS runs the new CF Standard Name table through some checking scripts +and then publishes them overnight (many thanks are due to our BODC colleagues, +especially Gwen Moncoiffe and Alexandra Kokkinaki for this part of the process). + +### KWIC Index + +The KWIC Index version of standard names is produced by first running a Unix shell script +to do some simple text editing on the XML file, +then feeding the result into a Prolog program +contributed by Robert Meutzelfeldt from the University of Edinburgh. +(This is done manually and is not part of the CEDA vocab editor). +The process generates the KWIC Index as an HTML file. ## CF Standardized Region List ?? + +[cf-discuss]: https://github.com/cf-convention/discuss \ No newline at end of file From cdd5659bfd8ea504eca81d000beebee8b34d9d21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antonio=20S=2E=20Cofi=C3=B1o?= Date: Wed, 2 Oct 2024 14:04:36 +0200 Subject: [PATCH 4/6] Update infrastructure-guide.md Improve the CF website intro --- infrastructure-guide.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/infrastructure-guide.md b/infrastructure-guide.md index baa006b93..f6dc35653 100644 --- a/infrastructure-guide.md +++ b/infrastructure-guide.md @@ -7,11 +7,10 @@ and standardized region list. ## CF Website -The [CF Website](http://cfconventions.org) is served by GitHub Pages -from source documents (in Markdown mainly) on the `master` branch +The [CF Website](https://cfconventions.org) is served by [GitHub Pages](https://pages.github.com/) as static site generated by [Jekyll](https://jekyllrb.com/), and rendered from source files in [Markdown](https://github.github.com/gfm/) (mainly) on the `main` branch of the [CF Website repo](https://github.com/cf-convention/cf-convention.github.io). -The CF Website pages are regenerated automatically by GitHub Pages -whenever a commit is made to the `master` branch. + +The CF Website site pages are regenerated automatically by [GitHub Action](https://docs.github.com/en/actions) whenever a commit is made to the `main` branch. ### PR Testing for the CF Website @@ -103,4 +102,4 @@ The process generates the KWIC Index as an HTML file. ?? -[cf-discuss]: https://github.com/cf-convention/discuss \ No newline at end of file +[cf-discuss]: https://github.com/cf-convention/discuss From b5e57a7ce8b567e6db0e3cf3a56a0a239f0eff36 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antonio=20S=2E=20Cofi=C3=B1o?= Date: Wed, 2 Oct 2024 14:07:23 +0200 Subject: [PATCH 5/6] Update infrastructure-guide.md Update `master` to `main` --- infrastructure-guide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/infrastructure-guide.md b/infrastructure-guide.md index f6dc35653..f4c044196 100644 --- a/infrastructure-guide.md +++ b/infrastructure-guide.md @@ -21,13 +21,13 @@ from the CF Website repo's GitHub Actions [page](https://github.com/cf-conventio for the build of that PR. Configuration files are: -- [`check_jekyll_build.yml`](https://github.com/cf-convention/cf-convention.github.io/blob/master/.github/workflows/check_jekyll_build.yml) -- [`Gemfile`](https://github.com/cf-convention/cf-convention.github.io/blob/master/Gemfile) -- [`_config.yml`](https://github.com/cf-convention/cf-convention.github.io/blob/master/_config.yml) +- [`check_jekyll_build.yml`](https://github.com/cf-convention/cf-convention.github.io/blob/main/.github/workflows/check_jekyll_build.yml) +- [`Gemfile`](https://github.com/cf-convention/cf-convention.github.io/blob/main/Gemfile) +- [`_config.yml`](https://github.com/cf-convention/cf-convention.github.io/blob/main/_config.yml) ## CF Conventions Document The CF Conventions Document is built from source documents (in AsciiDoc) -on the `master` branch of the [CF Conventions repo](https://github.com/cf-convention/cf-conventions). +on the `main` branch of the [CF Conventions repo](https://github.com/cf-convention/cf-conventions). ### Draft Version - Including all Accepted Proposals For each commit to the `master` branch of the CF Conventions repo, @@ -56,7 +56,7 @@ using Asciidoctor. The resulting HTML page and PDF document are available as artifacts in each build on the CF Conventions repo GitHub Actions [page](https://github.com/cf-convention/cf-conventions/actions). The configuration file for this GitHub Action is: -- [`check_adoc_build.yml`](https://github.com/cf-convention/cf-conventions/blob/master/.github/workflows/check_adoc_build.yml) +- [`check_adoc_build.yml`](https://github.com/cf-convention/cf-conventions/blob/main/.github/workflows/check_adoc_build.yml) ## CF Standard Names Table New CF Standard Names are proposed and discussed in issues on the From 1583c733c7e3b45e7ace0278313dee4638bc464c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antonio=20S=2E=20Cofi=C3=B1o?= Date: Wed, 2 Oct 2024 14:23:37 +0200 Subject: [PATCH 6/6] Update infrastructure-guide.md Updating some info about building pages --- infrastructure-guide.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/infrastructure-guide.md b/infrastructure-guide.md index f4c044196..6017e77a3 100644 --- a/infrastructure-guide.md +++ b/infrastructure-guide.md @@ -30,16 +30,18 @@ The CF Conventions Document is built from source documents (in AsciiDoc) on the `main` branch of the [CF Conventions repo](https://github.com/cf-convention/cf-conventions). ### Draft Version - Including all Accepted Proposals -For each commit to the `master` branch of the CF Conventions repo, -[Travis](https://travis-ci.org) builds the CF Conventions document(s) +For each commit to the `main` branch of the CF Conventions repo, +a GitHub Workflow builds the CF Conventions document(s) using [Asciidoctor](https://asciidoctor.org/). + The resulting HTML page and PDF document are pushed to the `gh-pages` branch -and are served by GitHub Pages at http://cfconventions.org/cf-conventions. -As only accepted proposals and fixes are pushed to master, the resulting documents +and are served by GitHub Pages at http://cfconventions.org/cf-conventions . +As only accepted proposals and fixes are pushed to `main`, the resulting documents are the draft version for the next release. ### Release Versions ??? Also done with Travis? Need to confirm this. +??? This also done in the same GitHub action as the Draft version, but special conditions are met when the event it's a `release` Resulting HTML page and PDF document are pushed to the CF Website Repo at `/Data/cf-conventions/cf-convention-`