commit 3c4f29d474b7f5c79ddbf01b4bb125e312973df4 parent 14e50853371ca2d904a94fbbb1768512fde5e540 Author: Andreas Gruhler <agruhl@gmx.ch> Date: Sat, 4 Dec 2021 14:40:05 +0100 rename docs files Diffstat:
| M | README.md | | | 7 | +++++-- |
| D | docs/CI.MD | | | 45 | --------------------------------------------- |
| A | docs/CI.md | | | 45 | +++++++++++++++++++++++++++++++++++++++++++++ |
| D | docs/OBS.MD | | | 142 | ------------------------------------------------------------------------------- |
| A | docs/OBS.md | | | 142 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| R | docs/TESTING.MD -> docs/TESTING.md | | | 0 |
6 files changed, 192 insertions(+), 189 deletions(-)
diff --git a/README.md b/README.md @@ -98,10 +98,13 @@ Note: for *BSD users run gmake. You can uninstall diary with `sudo make uninstall`. ## OBS Build Documentation -[./docs/OBS.MD](./docs/OBS.MD) +[./docs/OBS.md](./docs/OBS.md) ## GitHub Action CI Documentation -[./docs/CI.MD](./docs/CI.MD) +[./docs/CI.md](./docs/CI.md) + +## Test Documentation +[./docs/TESTING.md](./docs/TESTING.md) ## Configuration File diff --git a/docs/CI.MD b/docs/CI.MD @@ -1,45 +0,0 @@ -# Documentation of CI Jobs - -## OpenSuse Build Service Nightly Builds from Master -`push` events on the `master` branch trigger a rebuild of the [`diary-nightly`](https://build.opensuse.org/package/show/home:in0rdr/diary-nightly) package in the OpenSuse Build Service (see [./OBS.MD](./OBS.MD) for a description of the OBS builds). - -These jobs are called "workflows" in the OpenSuse Build Service and they are stored at [`.obs/workflows.yml`](../.obs/workflows.yml). - -The documentation for this kind of "workflow" can be found in the [GitHub repository of the Open Build Service](https://github.com/openSUSE/open-build-service/wiki/Better-SCM-CI-Integration) and in a [series of blog posts on "SCM integration"](https://openbuildservice.org/blog). - -A new chapter in the documentation was written Nov 2021 which explains the purpose and usage of OBS workflows in detail: -https://openbuildservice.org/help/manuals/obs-user-guide/cha.obs.scm_ci_workflow_integration.html - -### Create OBS Workflow Token - -The `$token` is a 40 char [personal Git access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -A workflow token can be created as follows: -```bash -# https://openbuildservice.org/2021/05/31/scm-integration/ -$ osc api -X POST "/person/in0rdr/token?project=home:in0rdr&package=diary-nightly&operation=workflow&scm_token=$token" -``` - -To list existing tokens, visit: -https://build.opensuse.org/my/tokens - -Or list via CLI: -```bash -$ osc token list -``` - -The value of the token is configured on the VCS side. - -## GitHub Action to Verify Build - -[`.github/workflows/c.yml`](../.github/workflows/c.yml) implements a GitHub action to run the simple series of build steps (`make && make install`) for new commits and pull requests on the `master` branch. - -[`.github/c/make-install/action.yml`](../.github/c/make-install/action.yml) is a re-usable action (dependency). - -## GitHub Action to Render Man Page - -[`.github/workflows/man.yml`](../.github/workflows/man.yml) is a job to render a new version of the man page after each commit or pull request on the `master` branch. - -This file is consumed by a Terraform job and rendered at https://diary.in0rdr.ch/man. - -A refresh of the html file in this GitHub repository does not automatically refresh the man page on the website (manual step). diff --git a/docs/CI.md b/docs/CI.md @@ -0,0 +1,45 @@ +# Documentation of CI Jobs + +## OpenSuse Build Service Nightly Builds from Master +`push` events on the `master` branch trigger a rebuild of the [`diary-nightly`](https://build.opensuse.org/package/show/home:in0rdr/diary-nightly) package in the OpenSuse Build Service (see [./OBS.md](./OBS.md) for a description of the OBS builds). + +These jobs are called "workflows" in the OpenSuse Build Service and they are stored at [`.obs/workflows.yml`](../.obs/workflows.yml). + +The documentation for this kind of "workflow" can be found in the [GitHub repository of the Open Build Service](https://github.com/openSUSE/open-build-service/wiki/Better-SCM-CI-Integration) and in a [series of blog posts on "SCM integration"](https://openbuildservice.org/blog). + +A new chapter in the documentation was written Nov 2021 which explains the purpose and usage of OBS workflows in detail: +https://openbuildservice.org/help/manuals/obs-user-guide/cha.obs.scm_ci_workflow_integration.html + +### Create OBS Workflow Token + +The `$token` is a 40 char [personal Git access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). + +A workflow token can be created as follows: +```bash +# https://openbuildservice.org/2021/05/31/scm-integration/ +$ osc api -X POST "/person/in0rdr/token?project=home:in0rdr&package=diary-nightly&operation=workflow&scm_token=$token" +``` + +To list existing tokens, visit: +https://build.opensuse.org/my/tokens + +Or list via CLI: +```bash +$ osc token list +``` + +The value of the token is configured on the VCS side. + +## GitHub Action to Verify Build + +[`.github/workflows/c.yml`](../.github/workflows/c.yml) implements a GitHub action to run the simple series of build steps (`make && make install`) for new commits and pull requests on the `master` branch. + +[`.github/c/make-install/action.yml`](../.github/c/make-install/action.yml) is a re-usable action (dependency). + +## GitHub Action to Render Man Page + +[`.github/workflows/man.yml`](../.github/workflows/man.yml) is a job to render a new version of the man page after each commit or pull request on the `master` branch. + +This file is consumed by a Terraform job and rendered at https://diary.in0rdr.ch/man. + +A refresh of the html file in this GitHub repository does not automatically refresh the man page on the website (manual step). diff --git a/docs/OBS.MD b/docs/OBS.MD @@ -1,142 +0,0 @@ -# Documentation for OBS Builds - -The OBS project [`home:in0rdr`](https://build.opensuse.org/project/show/home:in0rdr) comprises following `diary` packages: -* `diary`: Latest stable release built from tar.gz statically placed in the source -* `diary-nightly`: Latest unstable build, re-built dynamically from the code on the GitHub master branch (see [./CI.MD](./CI.MD) for a description of the GitHub Actions) - -> ℹ️ `diary-nightly` is not branched from `diary`, it has a completely separate build config. - -Additionally, these packages are being used as dependency for `diary-nightly`, to download the latest diary source code from the GitHub master branch: -* [`openSUSE:Tools/obs-service-tar_scm`](https://github.com/openSUSE/obs-service-tar_scm): Use `obs_scm` to fetch latest GitHub sources - -* [`openSUSE:Tools/obs-service-recompress`](https://github.com/openSUSE/obs-service-recompress): Re-compress downloaded GitHub source files -* [`openSUSE:Tools/obs-service-set_version`](https://github.com/openSUSE/obs-service-set_version): Set dynamic version based on information (`.obsinfo` file) from the GitHub checkout - -## OBS Project Configuration - -``` -# Disable obs_scm_testsuite for obs-service-set_version: -# https://github.com/openSUSE/obs-service-set_version/issues/64 -Macros: -%_without_obs_scm_testsuite 1 -:Macros - -# Fix "have choice for libzstd.so.1()(64bit) needed by rpm-build: libzstd libzstd1" -# https://en.opensuse.org/openSUSE:Build_Service_prjconf#Prefer -Prefer: libzstd -``` - -## OBS Source Services (`obs-service-`) Documentation - -The documentation on how to use source services is sparse and scattered: - -* https://openbuildservice.org/help/manuals/obs-user-guide/cha.obs.source_service.html -* https://github.com/openSUSE/obs-service-tar_scm/issues/238 -* https://github.com/openSUSE/obs-service-tar_scm/issues/223 -* https://build.opensuse.org/package/view_file/OBS:Server:Unstable/obs-service-tar_scm/_service?expand=1 - -The purpose of the source services and how they are used for the `diary-nightly` build (dependencies) is documented below. - -### `openSUSE:Tools/obs-service-tar_scm` - -Fix build for CentOS 8 by applying this patch in `obs-service-tar_scm.spec`: -* https://github.com/openSUSE/obs-service-tar_scm/issues/374 -* https://github.com/olegantonyan/obs-service-tar_scm/commit/6a454aa71395ca03a737d795551ba027a5f8a9e3 - -```diff - %if %{with python3} -+ -+ %if 0%{?centos_version} >= 800 -+ # ignore python3 dependency (nothing provides python3 error) -+ %else - BuildRequires: %{use_python}%{_pkg_base} -+ %endif -``` - -Manual download of latest release: -https://github.com/openSUSE/obs-service-tar_scm/tags - -* Use a simple filename and version, such as `obs-service-tar_scm-0.10.29.tar.gz `. -* Adjust the version numbers in the build files. - -Applying the latest version fixes the following issue: -``` -[ 2s] Running build time source services... -[ 2s] Preparing sources... -[ 2s] ==> WARNING: Skipping verification of source file PGP signatures. -[ 2s] obs-service-tar_scm-0.10.28.1632141620.a8837d3.tar.gz ... Skipped -[ 2s] bsdtar: Failed to set default locale -[ 2s] bsdtar: Pathname can't be converted from UTF-8 to current locale. -[ 2s] bsdtar: Error exit delayed from previous errors. -[ 2s] ==> ERROR: Failed to extract obs-service-tar_scm-0.10.28.1632141620.a8837d3.tar.gz -[ 2s] Aborting... -[ 2s] failed to prepare sources -``` - -The following patch might be related (needs to be applied OBS server-side, nothing left to do): -https://github.com/openSUSE/obs-build/pull/696 - -### `openSUSE:Tools/obs-service-recompress` - -https://github.com/openSUSE/obs-service-recompress - -Branched package from [`openSUSE:Tools/obs-service-recompress`](https://build.opensuse.org/package/show/openSUSE:Tools/obs-service-recompress). - -If this package is not made available in the local project `home:in0rdr`, following error message will occur: -``` -nothing provides obs-service-recompress -``` - -No further modifications needed, but needs to be available for the `diary-nightly` for compression services: -```bash -# home:in0rdr/diary-nightly/_service -<services> - <service mode="buildtime" name="recompress"> - <param name="file">*.tar</param> - <param name="compression">gz</param> - </service> -... -</services> -``` - -This service is used in combination with the service [`tar_scm`](https://github.com/openSUSE/obs-service-tar_scm). - -### `openSUSE:Tools/obs-service-set_version` - -This service sets the version in the RPM spec or Debian changelog according to the latest source files downloaded from GitHub: -https://github.com/openSUSE/obs-service-set_version - -### `openSUSE:Factory/zstd` OBS Package - -> ℹ️ This OBS package is not strictly required (no branching needed) with `tar.gz` compression in the source service (`_service`). - -Patch `zstd.spec`, such that RHEL build require `glibc-static` and openSUSE builds require `glibc-devel-static`: -```diff -- BuildRequires: (glibc-static or glibc-devel-static) -+ %if 0%{?rhel} || 0%{?fedora} -+ BuildRequires: glibc-static -+ %else -+ BuildRequires: glibc-devel-static -+ %endif -``` - -## `zstd` Compression in the ArchLinux PKGBUILD - -If `diary-nightly` for ArchLinux is built with `tar.gz` compression, the build will not be shown on the [download page](https://software.opensuse.org//download.html?project=home%3Ain0rdr&package=diary-nightly) and the download button for ArchLinux is missing, see also: -* https://github.com/in0rdr/diary/issues/64 -* https://github.com/openSUSE/software-o-o/issues/844 -* https://github.com/openSUSE/open-build-service/pull/10570 -* https://archlinux.org/news/now-using-zstandard-instead-of-xz-for-package-compression - -Therefore, build the ArchLinux package with the `.pkg.tar.zst` extension/compression: - -``` -# ./diary-nightly/PKGBUILD -PKGEXT='.pkg.tar.zst' -``` - -If the ZST compression (new defacto standard since [2020-01-04](https://archlinux.org/news/now-using-zstandard-instead-of-xz-for-package-compression)) does not work, use the xz compression as an alternative as described in [openSUSE/software-o-o/#844](https://github.com/openSUSE/software-o-o/issues/844): - -``` -PKGEXT='.pkg.tar.xz' -``` diff --git a/docs/OBS.md b/docs/OBS.md @@ -0,0 +1,142 @@ +# Documentation for OBS Builds + +The OBS project [`home:in0rdr`](https://build.opensuse.org/project/show/home:in0rdr) comprises following `diary` packages: +* `diary`: Latest stable release built from tar.gz statically placed in the source +* `diary-nightly`: Latest unstable build, re-built dynamically from the code on the GitHub master branch (see [./CI.md](./CI.md) for a description of the GitHub Actions) + +> ℹ️ `diary-nightly` is not branched from `diary`, it has a completely separate build config. + +Additionally, these packages are being used as dependency for `diary-nightly`, to download the latest diary source code from the GitHub master branch: +* [`openSUSE:Tools/obs-service-tar_scm`](https://github.com/openSUSE/obs-service-tar_scm): Use `obs_scm` to fetch latest GitHub sources + +* [`openSUSE:Tools/obs-service-recompress`](https://github.com/openSUSE/obs-service-recompress): Re-compress downloaded GitHub source files +* [`openSUSE:Tools/obs-service-set_version`](https://github.com/openSUSE/obs-service-set_version): Set dynamic version based on information (`.obsinfo` file) from the GitHub checkout + +## OBS Project Configuration + +``` +# Disable obs_scm_testsuite for obs-service-set_version: +# https://github.com/openSUSE/obs-service-set_version/issues/64 +Macros: +%_without_obs_scm_testsuite 1 +:Macros + +# Fix "have choice for libzstd.so.1()(64bit) needed by rpm-build: libzstd libzstd1" +# https://en.opensuse.org/openSUSE:Build_Service_prjconf#Prefer +Prefer: libzstd +``` + +## OBS Source Services (`obs-service-`) Documentation + +The documentation on how to use source services is sparse and scattered: + +* https://openbuildservice.org/help/manuals/obs-user-guide/cha.obs.source_service.html +* https://github.com/openSUSE/obs-service-tar_scm/issues/238 +* https://github.com/openSUSE/obs-service-tar_scm/issues/223 +* https://build.opensuse.org/package/view_file/OBS:Server:Unstable/obs-service-tar_scm/_service?expand=1 + +The purpose of the source services and how they are used for the `diary-nightly` build (dependencies) is documented below. + +### `openSUSE:Tools/obs-service-tar_scm` + +Fix build for CentOS 8 by applying this patch in `obs-service-tar_scm.spec`: +* https://github.com/openSUSE/obs-service-tar_scm/issues/374 +* https://github.com/olegantonyan/obs-service-tar_scm/commit/6a454aa71395ca03a737d795551ba027a5f8a9e3 + +```diff + %if %{with python3} ++ ++ %if 0%{?centos_version} >= 800 ++ # ignore python3 dependency (nothing provides python3 error) ++ %else + BuildRequires: %{use_python}%{_pkg_base} ++ %endif +``` + +Manual download of latest release: +https://github.com/openSUSE/obs-service-tar_scm/tags + +* Use a simple filename and version, such as `obs-service-tar_scm-0.10.29.tar.gz `. +* Adjust the version numbers in the build files. + +Applying the latest version fixes the following issue: +``` +[ 2s] Running build time source services... +[ 2s] Preparing sources... +[ 2s] ==> WARNING: Skipping verification of source file PGP signatures. +[ 2s] obs-service-tar_scm-0.10.28.1632141620.a8837d3.tar.gz ... Skipped +[ 2s] bsdtar: Failed to set default locale +[ 2s] bsdtar: Pathname can't be converted from UTF-8 to current locale. +[ 2s] bsdtar: Error exit delayed from previous errors. +[ 2s] ==> ERROR: Failed to extract obs-service-tar_scm-0.10.28.1632141620.a8837d3.tar.gz +[ 2s] Aborting... +[ 2s] failed to prepare sources +``` + +The following patch might be related (needs to be applied OBS server-side, nothing left to do): +https://github.com/openSUSE/obs-build/pull/696 + +### `openSUSE:Tools/obs-service-recompress` + +https://github.com/openSUSE/obs-service-recompress + +Branched package from [`openSUSE:Tools/obs-service-recompress`](https://build.opensuse.org/package/show/openSUSE:Tools/obs-service-recompress). + +If this package is not made available in the local project `home:in0rdr`, following error message will occur: +``` +nothing provides obs-service-recompress +``` + +No further modifications needed, but needs to be available for the `diary-nightly` for compression services: +```bash +# home:in0rdr/diary-nightly/_service +<services> + <service mode="buildtime" name="recompress"> + <param name="file">*.tar</param> + <param name="compression">gz</param> + </service> +... +</services> +``` + +This service is used in combination with the service [`tar_scm`](https://github.com/openSUSE/obs-service-tar_scm). + +### `openSUSE:Tools/obs-service-set_version` + +This service sets the version in the RPM spec or Debian changelog according to the latest source files downloaded from GitHub: +https://github.com/openSUSE/obs-service-set_version + +### `openSUSE:Factory/zstd` OBS Package + +> ℹ️ This OBS package is not strictly required (no branching needed) with `tar.gz` compression in the source service (`_service`). + +Patch `zstd.spec`, such that RHEL build require `glibc-static` and openSUSE builds require `glibc-devel-static`: +```diff +- BuildRequires: (glibc-static or glibc-devel-static) ++ %if 0%{?rhel} || 0%{?fedora} ++ BuildRequires: glibc-static ++ %else ++ BuildRequires: glibc-devel-static ++ %endif +``` + +## `zstd` Compression in the ArchLinux PKGBUILD + +If `diary-nightly` for ArchLinux is built with `tar.gz` compression, the build will not be shown on the [download page](https://software.opensuse.org//download.html?project=home%3Ain0rdr&package=diary-nightly) and the download button for ArchLinux is missing, see also: +* https://github.com/in0rdr/diary/issues/64 +* https://github.com/openSUSE/software-o-o/issues/844 +* https://github.com/openSUSE/open-build-service/pull/10570 +* https://archlinux.org/news/now-using-zstandard-instead-of-xz-for-package-compression + +Therefore, build the ArchLinux package with the `.pkg.tar.zst` extension/compression: + +``` +# ./diary-nightly/PKGBUILD +PKGEXT='.pkg.tar.zst' +``` + +If the ZST compression (new defacto standard since [2020-01-04](https://archlinux.org/news/now-using-zstandard-instead-of-xz-for-package-compression)) does not work, use the xz compression as an alternative as described in [openSUSE/software-o-o/#844](https://github.com/openSUSE/software-o-o/issues/844): + +``` +PKGEXT='.pkg.tar.xz' +``` diff --git a/docs/TESTING.MD b/docs/TESTING.md