From 2af44cf2d7670b863a83664e4e03e6c9b6167b17 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Thu, 9 Nov 2023 14:43:52 +0100 Subject: [PATCH 1/3] prefer 'adding_software' over 'contributing_sw' in docs URL + fix /adding_software broken URL using auto-redirect --- .../building_software.md | 4 +++- .../contribution_policy.md | 0 .../debugging_failed_builds.md | 4 +++- .../deploying_software.md | 4 +++- .../opening_pr.md | 4 +++- docs/adding_software/overview.md | 7 +++++++ docs/bot.md | 4 ++-- docs/contributing_sw/overview.md | 3 --- docs/support.md | 2 +- mkdocs.yml | 21 +++++++++++++------ 10 files changed, 37 insertions(+), 16 deletions(-) rename docs/{contributing_sw => adding_software}/building_software.md (98%) rename docs/{contributing_sw => adding_software}/contribution_policy.md (100%) rename docs/{contributing_sw => adding_software}/debugging_failed_builds.md (99%) rename docs/{contributing_sw => adding_software}/deploying_software.md (97%) rename docs/{contributing_sw => adding_software}/opening_pr.md (98%) create mode 100644 docs/adding_software/overview.md delete mode 100644 docs/contributing_sw/overview.md diff --git a/docs/contributing_sw/building_software.md b/docs/adding_software/building_software.md similarity index 98% rename from docs/contributing_sw/building_software.md rename to docs/adding_software/building_software.md index c7c585b08..7e39e5b3a 100644 --- a/docs/contributing_sw/building_software.md +++ b/docs/adding_software/building_software.md @@ -1,4 +1,6 @@ -# Building software (maintainers) +# Building software + +*(for maintainers)* ### Instructing the bot to build :hammer: { #bot_build } diff --git a/docs/contributing_sw/contribution_policy.md b/docs/adding_software/contribution_policy.md similarity index 100% rename from docs/contributing_sw/contribution_policy.md rename to docs/adding_software/contribution_policy.md diff --git a/docs/contributing_sw/debugging_failed_builds.md b/docs/adding_software/debugging_failed_builds.md similarity index 99% rename from docs/contributing_sw/debugging_failed_builds.md rename to docs/adding_software/debugging_failed_builds.md index ff2cdbba3..cf4834c4e 100644 --- a/docs/contributing_sw/debugging_failed_builds.md +++ b/docs/adding_software/debugging_failed_builds.md @@ -1,4 +1,6 @@ -# Debugging failed builds (contributors/maintainers) +# Debugging failed builds + +*(for contributors + maintainers)* Unfortunately, software does not always build successfully. Since EESSI targets novel CPU architectures as well, build failures on such platforms are quite common, as the software and/or the software build systems have not always been adjusted to support these architectures yet. diff --git a/docs/contributing_sw/deploying_software.md b/docs/adding_software/deploying_software.md similarity index 97% rename from docs/contributing_sw/deploying_software.md rename to docs/adding_software/deploying_software.md index afd5f5639..26f824ae6 100644 --- a/docs/contributing_sw/deploying_software.md +++ b/docs/adding_software/deploying_software.md @@ -1,4 +1,6 @@ -# Deploying packages (maintainers) +# Deploying software + +*(for maintainers)* ### Instructing the bot to deploy :rocket: diff --git a/docs/contributing_sw/opening_pr.md b/docs/adding_software/opening_pr.md similarity index 98% rename from docs/contributing_sw/opening_pr.md rename to docs/adding_software/opening_pr.md index 6c69f703e..ce82b68f0 100644 --- a/docs/contributing_sw/opening_pr.md +++ b/docs/adding_software/opening_pr.md @@ -1,4 +1,6 @@ -# Opening a pull request (contributors) +# Opening a pull request + +*(for contributors)* To add software to EESSI, you should go through the semi-automatic software installation procedure by: diff --git a/docs/adding_software/overview.md b/docs/adding_software/overview.md new file mode 100644 index 000000000..cc9cd1167 --- /dev/null +++ b/docs/adding_software/overview.md @@ -0,0 +1,7 @@ +# Adding software to EESSI + +* [Contribution policy](contribution_policy.md) +* [Opening a pull request *(for contributors)*](opening_pr.md) +* [Building software *(for maintainers)*](building_software.md) +* [Debugging failed builds *(for contributors + maintainers)*](debugging_failed_builds.md) +* [Deploying software *(for maintainers)*](deploying_software.md) diff --git a/docs/bot.md b/docs/bot.md index 4e6d40377..64707a4b4 100644 --- a/docs/bot.md +++ b/docs/bot.md @@ -6,7 +6,7 @@ Building, testing, and deploying software is done by one or more *bot instances* The EESSI build-test-deploy bot :robot: is implemented as a [GitHub App](https://docs.github.com/en/apps/overview) in the [`eessi-bot-software-layer` repository](https://github.com/EESSI/eessi-bot-software-layer). -It operates in the context of [pull requests](contributing_sw/opening_pr.md#software_layer_pull_request) to +It operates in the context of [pull requests](adding_software/opening_pr.md#software_layer_pull_request) to the [`compatibility-layer` repository](https://github.com/EESSI/compatibility-layer) or the [`software-layer` repository](https://github.com/EESSI/software-layer), and follows the instructions supplied by humans, @@ -61,7 +61,7 @@ to trigger building of software, and to deploy software installations in to the ## Building { #building } To instruct the bot :robot: to build software, one or more `build` instructions -should be issued by posting a comment in the pull request (see also [here](contributing_sw/building_software.md#bot_build)). +should be issued by posting a comment in the pull request (see also [here](adding_software/building_software.md#bot_build)). The most basic build instruction that can be sent to the bot is: diff --git a/docs/contributing_sw/overview.md b/docs/contributing_sw/overview.md deleted file mode 100644 index aead25af5..000000000 --- a/docs/contributing_sw/overview.md +++ /dev/null @@ -1,3 +0,0 @@ -# Overview - -This page will display an overview of the procedure of contributing software to the EESSI software stack (coming soon). diff --git a/docs/support.md b/docs/support.md index d38ab92ec..6e4f7a758 100644 --- a/docs/support.md +++ b/docs/support.md @@ -38,7 +38,7 @@ Note that we can only help with problems related to the software *installations* We are open to software requests for software that is not included in EESSI yet. -The quickest way to add additional software to EESSI is by contributing it yourself as a community contribution, please see the [documentation on adding software](contributing_sw/overview.md). +The quickest way to add additional software to EESSI is by contributing it yourself as a community contribution, please see the [documentation on adding software](adding_software/overview.md). Alternatively, you can send in a request to our support team. Please try to provide as much information on the software as possible: preferably use the [issue template](https://gitlab.com/eessi/support/-/issues/new?issuable_template=Software_request) (which requires you to log in to GitLab), or make sure to cover the items listed [here](https://gitlab.com/eessi/support/-/blob/main/.gitlab/issue_templates/Software_request.md). diff --git a/mkdocs.yml b/mkdocs.yml index f0a0707b8..46758a5b4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,13 +43,13 @@ nav: - using_eessi/eessi_demos.md - Adding software to EESSI: # Todo: insert an overview page with a flowchart showing the high level process - - contributing_sw/overview.md + - (overview): adding_software/overview.md # - Contribution policy, requires #108 - - contributing_sw/contribution_policy.md - - contributing_sw/opening_pr.md - - contributing_sw/building_software.md - - contributing_sw/debugging_failed_builds.md - - contributing_sw/deploying_software.md + - adding_software/contribution_policy.md + - adding_software/opening_pr.md + - adding_software/building_software.md + - adding_software/debugging_failed_builds.md + - adding_software/deploying_software.md # Todo: write on how to contribute to the EESSI test suite # - Contributing software tests to the EESSI test suite: - Getting support: support.md @@ -63,6 +63,15 @@ plugins: - git-revision-date-localized # necessary for search to work - search + - redirects: + redirect_maps: + adding_software.md: adding_software/overview.md + contributing_sw/building_software.md: adding_software/building_software.md + contributing_sw/contribution_policy.md: adding_software/contribution_policy.md + contributing_sw/debugging_failed_builds.md: adding_software/debugging_failed_builds.md + contributing_sw/deploying_software.md: adding_software/deploying_software.md + contributing_sw/opening_pr.md: adding_software/opening_pr.md + contributing_sw/overview.md: adding_software/overview.md markdown_extensions: # enable adding HTML attributes and CSS classes - attr_list From a9eb2251ec547975ff78130c9c376450813de077 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Thu, 9 Nov 2023 15:05:34 +0100 Subject: [PATCH 2/3] also add redirect for docs/software_layer/adding_software URL --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 46758a5b4..94bd39638 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -72,6 +72,7 @@ plugins: contributing_sw/deploying_software.md: adding_software/deploying_software.md contributing_sw/opening_pr.md: adding_software/opening_pr.md contributing_sw/overview.md: adding_software/overview.md + software_layer/adding_software.md: adding_software/overview.md markdown_extensions: # enable adding HTML attributes and CSS classes - attr_list From bc71d96dac66cae0bc0edc920af0f304d1aa7bc3 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Thu, 9 Nov 2023 16:29:56 +0100 Subject: [PATCH 3/3] add requirements.txt to install mkdocs plugins (incl. mkdocs-redirects) --- .github/workflows/deploy.yml | 5 +++-- .github/workflows/test.yml | 5 +++-- requirements.txt | 5 +++++ 3 files changed, 11 insertions(+), 4 deletions(-) create mode 100644 requirements.txt diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 76db42c2c..38db175d5 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -22,9 +22,10 @@ jobs: with: python-version: '3.10' - - name: install mkdocs + - name: install mkdocs + plugins run: | - pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-toc-sidebar-plugin + pip install -r requirements.txt + pip list | grep mkdocs mkdocs --version - name: build tutorial diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index df3749ca9..2a07996bf 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -28,9 +28,10 @@ jobs: # config: '/lint/config/changelog.yml' # args: '.' - - name: install mkdocs + - name: install mkdocs + plugins run: | - pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-toc-sidebar-plugin + pip install -r requirements.txt + pip list | grep mkdocs mkdocs --version - name: build tutorial diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 000000000..cc56811d9 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,5 @@ +mkdocs +mkdocs-material +mkdocs-redirects +mkdocs-git-revision-date-localized-plugin +mkdocs-toc-sidebar-plugin