Create introduction to CI on website

docs/Comparison-of-CI-platforms.md

@@ -0,0 +1,71 @@
+There are a variety of CI platforms available today, so projects need to decide which platform or platforms to use.
+I strongly recommend that, at least for tests, the CI scripts are run on as many Common Lisp implementations as possible, and on OSX and Windows in addition to Linux, to improve the portability of your project.
+My basic recommendation for which CI platform to use is Travis CI for Linux and OSX and Appveyor for Windows.
+These platforms are well documented and are commonly used platforms for open source projects.
+
+Currently, CI-Utils supports 6 CI platforms, all of which have cloud hosting and free plans for open source software.
+A brief description of each is listed below for comparison purposes.
+If there is another platform that you are interested in, please raise a pull request or issue and we can work through adding support and documentation.
+
+| Platform | OS | Supported Repository Hosts |
+| -------- | -- | -------------------------- |
+| [Travis CI](#travis-ci) | Linux, OSX | Github |
+| [Appveyor](#appveyor) | Windows | Github, Bitbucket, Gitlab, Azure Repos, and more |
+| [CircleCI](#circleci) | Linux, OSX (paid only) | Github, Bitbucket |
+| [Azure Pipelines](#azure-pipelines) | Linux, OSX, Windows | Github, Bitbucket, Azure Repos, and more |
+| [Gitlab CI](#gitlab-ci) | Linux | Gitlab, Github, Bitbucket, and more |
+| [Bitbucket Pipelines](#bitbucket-pipelines) | Linux | Bitbucket |
+
+
+### Travis CI
+Travis CI is one of the oldest cloud hosted CI platforms, and thus is well documented and has plenty of examples.
+Unfortunately, only Github repositories are supported.
+Additionally, Travis only supports Linux and OSX, with OSX builds usually being slower due to a combination of limits on parallel jobs and homebrew needing to update a number of packages every time.
+Notably, Travis allows 5 Linux jobs and 2 OSX jobs to be run in parallel.
+Support for Windows is being developed; however, when tested, none of the Windows jobs were actually run.
+
+Travis is free for public repositories.
+Private repositories require payment (with a free trial).
+Additionally, Travis CI Enterprise provides an option for self hosting, as well as other quality of life benefits.
+
+### Appveyor
+Appveyor is another popular CI platform, with a focus Windows.
+It's oriented for development of native Windows code, but supports non-C/C++ projects just fine.
+Support for Linux jobs is documented; however, when tested it immediately failed to create the folder for the build.
+Appveyor supports a variety of repository hosts, allowing it to fit in many workflows.
+Finally, Appveyor offers self hosting to all users.
+
+Appveyor is free for public repositories and a single private repository.
+Paid accounts provide unlimited private repositories and running jobs in parallel.
+
+### CircleCI
+CircleCI is designed for performance and effective management of computing resources.
+Additionally, it provides the ability to run a single job multiple times in parallel.
+This allows a test suite, or other work load, to be parallelized, either manually using the `CIRCLE_NODE_TOTAL` and `CIRCLE_NODE_INDEX` environmental variables or their `circleci tests split` command.
+
+CircleCI provides a free plan with 1 Linux container for private projects as well as 4 Linux containers and 1 OSX container for public projects.
+Note that parallel jobs use multiple containers (i.e. 2x parallelism results in each job using 2 containers).
+Additionally, there are paid plans for increased numbers of containers, and a self hosted server.
+
+### Azure Pipelines
+Azure Pipelines is the CI service of Microsoft's Azure cloud computing offerings.
+Azure pipelines is the only one of these platforms that successfully supports all three major operating systems.
+Additionally, it is designed to integrate well with other Azure services.
+Azure Pipelines offers both cloud hosted and self hosted servers.
+
+Azure pipelines provides a free plan with 1 job at a time and up to 1,800 minutes per month for private projects, and 10 jobs in parallel for open source projects.
+There are also paid plans that allow for running more jobs in parallel and more build time.
+
+
+### Gitlab CI
+Gitlab provides a CI platform right out of the box for both cloud hosted and self hosted instances of Gitlab, including [gitlab.common-lisp.net](https://gitlab.common-lisp.net).
+Interestingly, Gitlab CI also allows, and even encourages, use of it's CI system for repositories not hosted in Gitlab, although this does involve a lightweight mirror of the repository.
+
+The only limitation of Gitlab's free account for CI purposes is a limit of 2,000 minutes per month when using the cloud hosted instance, and no restrictions for self hosted instances.
+
+### Bitbucket Pipelines
+Bitbucket pipelines is Bitbucket's CI offering.
+It doesn't provide any notable features compared to other platforms, but may be convenient for projects hosted on Bitbucket.
+
+The free plan only provides 50 minutes, although users with an academic email are able to get 500 minutes for free.
+Additionally, non-profit charities can apply for a community subscription that also provides 500 CI minutes.

docs/Introduction-to-CI.md

@@ -0,0 +1,54 @@
+---
+layout: page
+title: Introduction to CI Testing
+meta-description: A primer for testing Common Lisp libraries on Cloud CI platforms
+---
+
+Continuous Integration (CI) is the method of running tests, building binaries, and similar task after most committed modifications of a codebase, usually on a cloud platform or internal server for the project.
+This allows a project to ensure its tests are run regularly, and makes it obvious whenever the a change causes tests to break.
+Other tasks, such as building binaries or updating documentation can reduce the workload of developers while still maintaining those artifacts.
+The approach of continuous integration offers benefits to any project that has a series of steps taken after most (or specific types of) changes to the codebase.
+This introduction focuses more on running tests since that is the use case for most projects; however, the ideas and most of the tooling generalizes to other tasks.
+
+
+A quick note on styling, because uppercase I and lowercase L can look similar, the abbreviations CI and CL can look similar.
+To address this, a convention is used that both letters in these acronyms should always be the same case (i.e. CI means Continuous Integration, while Cl will never be used).
+
+
+Technically, the phrase "Continuous Integration" originally referred to integrating each developer's working copy of a codebase into the master copy on a regular basis to ensure that integrating the various changes doesn't become a monumental task.
+However, the phrase continuous integration more often used to describe automating scripts to run after changes to a codebase, and is used as such in this document and project.
+Some people use terms like "Continuous Deployment" and "Continuous Testing", especially if they want to emphasize a particular action that's taken (e.g. deployment and testing respectively).
+
+
+### Configuration Basics
+
+The rise of continuous integration tools for small and medium sized projects has been part of the rise of cloud computing and software as a service.
+There are a variety of cloud platforms that provide CI services; however, they all follow similar ideas for configuration and usage.
+The main method for configuring these platforms is to include a [YAML](https://yaml.org/) configuration file in the root directory of the repository named `.platform.yml` (i.e. `.travis.yml`).
+Some platforms have a different naming convention, or allow custom names.
+You can find example configuration files for most of CI-Util's supported platforms in its [config-examples](https://github.com/neil-lindquist/CI-Utils/tree/master/config-examples) directory.
+
+The term "build" is used to describe the entire set of scripts and actions that are run after a commit.
+Each build consists of a set of "jobs".
+The jobs divide the scripts and actions between separate containers.
+When running tests, each job will run the tests for one system configuration, such as a combination of lisp implementation and operating system.
+If any of the commands in a job fails (by having a non-zero return value), the entire job is marked as a failure and terminated.
+Similarly, if any jobs fail, the entire build is marked as a failure.
+This propagation of failures helps make it easy to determine if everything was successful.
+
+There are a couple of ways to keep an eye on the status of your builds.
+First, email notifications can be enabled, so that the results of builds are sent to one or more addresses.
+Usually, the frequency can be adjusted so that emails are only sent if the build fails, or if there is a change in the build's status.
+How notifications are configured and the types of notifications that are supported vary between platforms.
+The second main method to monitor build statuses is through badges on the repository's webpage or in it's README.
+For example, consider the live badge for CI-Utils on Travis CI: [![Travis Build Status](https://img.shields.io/travis/neil-lindquist/ci-utils.svg?logo=Travis)](https://travis-ci.org/neil-lindquist/CI-Utils), which hopefully tells you that the last build on Travis CI for CI-Utils passed.
+These badges are primarily used to show the status of tests, since they provide a convenient way to show people looking at the repository that there are tests that are run regularly, and whether those tests are passing.
+
+Some commits don't contain changes that require a new CI build.
+There are two major ways to tell CI platforms that the commit shouldn't be build.
+The first is to limit the branches and tags that CI should be run for, often specific jobs can be disabled outside specific branches/tags.
+This is specified in the configuration file, and varies significantly between platforms.
+Branch and tag limitations are primarily for limiting actions like building binaries or deploying documentation, which shouldn't happen on every commit.
+The second is to skip CI for a specific commit.
+To skip building on every platform, add `[skip ci]` to the commit's message.
+Alternatively, if CI should be skipped on only some platforms, most platforms obey `[skip <platform>]` in the commit message.

docs/_config.yml

@@ -13,6 +13,9 @@ description: Documentation for the CI-Utils Common Lisp library.
 # List of links in the navigation bar
 navbar-links:
   API Documentation: "API"
+  CI Basics:
+    Introduction to CI: "Introduction-to-CI"
+    Comparison of CI Platforms: "Comparison-of-CI-platforms"
 
 # Image to show in the navigation bar - image must be a square (width = height)
 # Remove this parameter if you don't want an image in the navbar