Upgrading ci configs to first class documents with licensing, cross-references to design, references, etc.

2026-04-27 16:51:06 -07:00 · 2023-01-15 19:14:35 +00:00 · 2023-01-15 19:14:35 +00:00 · 8f88a9ee8f
commit 8f88a9ee8f
parent 552acb3e85
3 changed files with 127 additions and 27 deletions
--- a/mps/.github/workflows/build-and-test.yml
+++ b/mps/.github/workflows/build-and-test.yml
@ -1,14 +1,14 @@
 # .github/workflows/build-and-test.yml -- GitHub CI build and test configuration for the MPS
 #
-# See design.mps.test.ci.github.
+# Copyright (c) 2019-2022 `GitHub contributors`_ (MIT License).
+# Copyright (c) 2023 Ravenbrook Limited. See end of file for license.
 #
-# [GitHub CI] "About continuous integration"; <https://docs.github.com/en/actions/automating-builds-and-tests/about-continuous-integration>.
-#
-# Adapted from <https://github.com/actions/starter-workflows/blob/9f245d9aba830ad16a097a45c78331a05114d815/ci/c-cpp.yml>
+# See design.mps.test.ci.
 #
 # TODO: Exclude certain branches.
 #
-# TODO: Regular builds of version branches.  See <https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onschedule>.
+# TODO: Regular builds of version branches.  See
+# <https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onschedule>.

 name: build and test

@ -23,13 +23,18 @@ jobs:

  posix:

+    # The build matrix for GitHub CI on Posix platforms
+    #
+    # See design.mps.tests.ci.github.platforms.
+    #
+    # FreeBSD and ARM64 targets are in Travis CI, configured by
+    # .travis.yml.
+    #
    # See <https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs#using-a-matrix-strategy>.
+    
    strategy:
      matrix:
-        # FreeBSD is built using Travis CI.  See .travis.yml.
        os: [ubuntu-latest, macos-latest]
-        # GitHub runners are only available on x86_64.
-        # arm64 is built using Travis CI.  See .travis.yml.
        compiler: [clang, gcc]
        exclude:
          - os: macos-latest
@ -37,6 +42,7 @@ jobs:

    runs-on: ${{ matrix.os }}

+    # See design.mps.tests.ci.run.posix.
    steps:
    - uses: actions/checkout@v3
    - run: CC=${{ matrix.compiler }} ./configure
@ -47,11 +53,60 @@ jobs:

    runs-on: windows-latest

+    # See design.mps.tests.ci.run.windows.
+    #
+    # The path to Visual Studio is documented at
+    # <https://github.com/actions/runner-images/blob/e6fcf60b8e6c0f80a065327eaefe836881c28b68/images/win/Windows2022-Readme.md?plain=1#L215>.
+
    steps:
    - uses: actions/checkout@v3
-    # Using path to Visual Studio documented at <https://github.com/actions/runner-images/blob/e6fcf60b8e6c0f80a065327eaefe836881c28b68/images/win/Windows2022-Readme.md?plain=1#L215>.
    - run: |
         call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvarsall.bat" x64
         cd code
         nmake /f w3i6mv.nmk all testci testansi testpollnone
      shell: cmd
+
+
+# A. REFERENCES
+#
+# [GitHub CI] "About continuous integration"; <https://docs.github.com/en/actions/automating-builds-and-tests/about-continuous-integration>.
+#
+# .. _GitHub contributors: https://github.com/actions/starter-workflows/commits/1d9d6d7fb0a8a27ef98efbbfa9689cd14c906383/ci/c-cpp.yml
+#
+#
+# B. DOCUMENT HISTORY
+#
+# 2023-01-11 RB Adapted from <https://github.com/actions/starter-workflows/blob/9f245d9aba830ad16a097a45c78331a05114d815/ci/c-cpp.yml>.
+# 2023-01-15 RB Added licence and document history.
+#
+#
+# C. COPYRIGHT AND LICENSE
+#
+# Copyright (C) 2013-2023 Ravenbrook Limited <https://www.ravenbrook.com/>.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the
+#    distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+#
+# $Id$
--- a/mps/.travis.yml
+++ b/mps/.travis.yml
@ -1,50 +1,52 @@
 # .travis.yml -- Travis CI configuration for the MPS
 #
-# See design.mps.test.ci.travis.
+# Copyright (c) 2013-2023 Ravenbrook Limited. See end of file for license.
 #
-# $Id$
+# See design.mps.test.ci.

 # Some branches don't need builds.  Add them here to avoid using build
 # resources and unnecessary build messages.  See
 # <https://docs.travis-ci.com/user/conditions-v1>.
 if: NOT branch IN (branch/2023-01-11/github-ci)

-# The main build matrix for POSIX-like systems.
 language: c # see <https://docs.travis-ci.com/user/languages/c/>.
+
+# The build matrix for Travis CI
+#
+# See design.mps.tests.ci.travis.platforms.
+#
+# Most x86_64/amd64 builds are in GitHub CI, configured by
+# .github/workflows/build-and-test.yml.
+
 os:
  - freebsd
  - linux
-  # If you include macOS here, Travis launches a redundant build on
-  # amd64, even though we specify arm64.  Perhaps it's because they
-  # don't support macOS on arm64.  When they do, try uncommenting
-  # this.
-  # - osx
-  # See "include" section for Windows
 arch:
-  # Most amd64 builds moved to GitHub CI.  See .github/workflows/build-and-test.yml.
-  # - amd64
  - arm64
 compiler:
  - clang
  - gcc
-script:
+
+script: # see design.mps.test.ci.run.posix
 - ./configure --prefix=$PWD/prefix && make install && make test

 matrix:
+
  # Extra build jobs to add to the matrix
  include:
-    # GitHub CI does not provide FreeBSD <https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources>.
+
+    # GitHub CI does not provide FreeBSD
+    # <https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources>
+    # on any architecture, so we add it here for amd64.  See also
+    # design.mps.tests.ci.travis.platforms.
+
    - os: freebsd
      arch: amd64
      compiler: clang
    - os: freebsd
      arch: amd64
      compiler: gcc
-    # Windows moved to GitHub CI.  See .github/workflows/c-cpp.yml.
-    #  - os: windows
-    #    arch: amd64
-    #    compiler: clang # This is a lie since we invoke MV (Microsoft C)
-    #    script: MSYS2_ARG_CONV_EXCL='*' cmd /c 'code\w3i6mv.bat'
+
  # Specific combinations to exclude from the matrix
  exclude:
    - os: osx
@ -58,3 +60,44 @@ notifications:
 #before_install:
 #  - if test "$TRAVIS_OS_NAME" = "linux"; then sudo apt-get -qq update; fi
 #  - if test "$TRAVIS_OS_NAME" = "linux"; then sudo apt-get install -y gcc-4.7; fi
+
+
+# A. REFERENCES
+#
+#
+# B. DOCUMENT HISTORY
+#
+# 2013-05-19 RB Created.
+# 2023-01-15 RB Added licence and (note) document history.
+#
+#
+# C. COPYRIGHT AND LICENSE
+#
+# Copyright (C) 2013-2023 Ravenbrook Limited <https://www.ravenbrook.com/>.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the
+#    distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+#
+# $Id$
--- a/mps/design/tests.txt
+++ b/mps/design/tests.txt
@ -292,6 +292,8 @@ requirements.  'taint really a design without this.  Mention how CI
 supports the pull request merge procedure (except that exists on a
 separate branch at the moment).  RB 2023-01-15]

+[Need to discuss compilers and toolchains.  RB 2023-01-15]
+
 _`.ci.run.posix`: On Posix systems where we have autoconf, the CI
 services run commands equivalent to::