Improve the ci directory documentation

Change the format to Markdown for better formatting on GitHub and
add documentation for the KDC setup scripts.

diff --git a/Makefile.am b/Makefile.am
index 935906f3dfa17a483dc96d0141ee0889cc61ee5e..564dc82d370e3bfc9e326b1653c4ad0c67308b10 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -11,17 +11,18 @@
 
 ACLOCAL_AMFLAGS = -I m4
 EXTRA_DIST = .clang-format .gitignore .github LICENSE README.md bootstrap   \
-       ci/README ci/files/heimdal/heimdal-kdc ci/files/heimdal/kadmind.acl \
-       ci/files/heimdal/kdc.conf ci/files/heimdal/krb5.conf                \
-       ci/files/heimdal/pki-mapping ci/files/mit/extensions.client         \
-       ci/files/mit/extensions.kdc ci/files/mit/kadm5.acl                  \
-       ci/files/mit/kdc.conf ci/files/mit/krb5.conf ci/kdc-setup-heimdal   \
-       ci/kdc-setup-mit ci/install ci/test docs/metadata docs/pam_krb5.pod \
-       module/pam_krb5.map module/pam_krb5.sym tests/README tests/TESTS    \
-       tests/config/README tests/data/cppcheck.supp                        \
-       tests/data/generate-krb5-conf tests/data/krb5-pam.conf              \
-       tests/data/krb5.conf tests/data/perl.conf tests/data/scripts        \
-       tests/data/valgrind.supp tests/docs/pod-spelling-t tests/docs/pod-t \
+       ci/README.md ci/files/heimdal/heimdal-kdc                           \
+       ci/files/heimdal/kadmind.acl ci/files/heimdal/kdc.conf              \
+       ci/files/heimdal/krb5.conf ci/files/heimdal/pki-mapping             \
+       ci/files/mit/extensions.client ci/files/mit/extensions.kdc          \
+       ci/files/mit/kadm5.acl ci/files/mit/kdc.conf ci/files/mit/krb5.conf \
+       ci/kdc-setup-heimdal ci/kdc-setup-mit ci/install ci/test            \
+       docs/metadata docs/pam_krb5.pod module/pam_krb5.map                 \
+       module/pam_krb5.sym tests/README tests/TESTS tests/config/README    \
+       tests/data/cppcheck.supp tests/data/generate-krb5-conf              \
+       tests/data/krb5-pam.conf tests/data/krb5.conf tests/data/perl.conf  \
+       tests/data/scripts tests/data/valgrind.supp                         \
+       tests/docs/pod-spelling-t tests/docs/pod-t                          \
        tests/docs/spdx-license-t tests/fakepam/README tests/tap/libtap.sh  \
        tests/tap/perl/Test/RRA.pm tests/tap/perl/Test/RRA/Automake.pm      \
        tests/tap/perl/Test/RRA/Config.pm tests/style/obsolete-strings-t    \

diff --git a/ci/README b/ci/README
deleted file mode 100644 (file)
index d41ca74..0000000
--- a/ci/README
+++ /dev/null
@@ -1,2 +0,0 @@
-The files in this directory are used for CI testing.  ci/install installs
-the prerequisite packages (run as root), and ci/test runs the tests.

diff --git a/ci/README.md b/ci/README.md
new file mode 100644 (file)
index 0000000..fedd0d5
--- /dev/null
+++ b/ci/README.md
@@ -0,0 +1,13 @@
+# Continuous Integration
+
+The files in this directory are used for continuous integration testing.
+`ci/install` installs the prerequisite packages (run as root on a Debian
+derivative), and `ci/test` runs the tests.
+
+Most tests will be skipped without a Kerberos configuration.  The scripts
+`ci/kdc-setup-heimdal` and `ci/kdc-setup-mit` will (when run as root on a
+Debian derivative) set up a Heimdal or MIT Kerberos KDC, respectively, and
+generate the files required to run the complete test suite.
+
+Tests are run automatically via GitHub Actions workflows using these
+scripts and the configuration in the `.github/workflows` directory.