diff --git a/docs/ci.rst b/docs/ci.rst new file mode 100644 index 0000000000..0918c1ab79 --- /dev/null +++ b/docs/ci.rst @@ -0,0 +1,69 @@ +.. _ci: + +Continuous Integration +====================== + +Bash-it uses `GitHub Actions `_ for Continuous Integration (CI). +The CI configuration is defined in ``.github/workflows/ci.yml``. + +Workflows +--------- + +The CI workflow is triggered on every ``push`` and ``pull_request`` event. + +Updating CI actions +------------------- + +Updating the CI workflow action should be done by pinning action to their sha commit and using a 10 days cooldown. +This can be done with `pinact `_: + +:: + + pinact run --update --min-age 10 + +Jobs +---- + +The CI process consists of the following jobs: + +Bats Test +^^^^^^^^^ + +This job runs the unit tests using the `Bats unit test framework `_. +The tests are executed on the following operating systems: + +* Ubuntu 24.04 +* macOS 14 + +Build Docs +^^^^^^^^^^ + +This job ensures that the documentation can be built successfully using `Sphinx `_. +It runs on ``ubuntu-latest`` and uses Python 3.12. + +Lint +^^^^ + +This job runs several linting tools to ensure code quality: + +* `shfmt `_: Checks shell script formatting. +* `shellcheck `_: A static analysis tool for shell scripts. +* `pre-commit `_: Runs all configured hooks in ``.pre-commit-config.yaml``. + +It runs on ``ubuntu-latest`` and uses Go and Python 3.12 to install the necessary tools. +The linting is performed using the ``./lint_clean_files.sh`` script, which checks files listed in ``clean_files.txt``. + +Lint Differential +^^^^^^^^^^^^^^^^^ + +This job runs a differential ShellCheck on pull requests, which only reports issues in the changed files. +It uses the `differential-shellcheck `_ action. + +Running CI checks locally +------------------------- + +Most of the CI checks can be run locally: + +* **Tests**: Run ``test/run`` (see :ref:`Testing Bash-it ` for more details). +* **Documentation**: Run ``sphinx-build -b html docs docs/_build/html`` (requires Sphinx and dependencies from ``docs/requirements.txt``). +* **Linting**: Run ``./lint_clean_files.sh`` (requires ``shfmt``, ``shellcheck``, and ``pre-commit``). diff --git a/docs/development.rst b/docs/development.rst index 4742e97139..2b626fc1dd 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -161,6 +161,15 @@ installing it (with pip, brew or other tools) then run ``pre-commit install`` in For the full use of the tool, you may need to install also other third-party tools, such as `shellcheck `_ and `shfmt `_. +Update pre-commit hooks +----------------------- + +Pre-commit hooks are pinned to the sha commit of the release with a 10 days cooldown. +You can update them with `prek `_: + +:: + + prek autoupdate --freeze --cooldown-days 10 .. _linting_your_changes: diff --git a/docs/index.rst b/docs/index.rst index 1fc3a5c27f..d93ceced5a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,6 +17,7 @@ Stop polluting your ``~/bin`` directory and your ``.bashrc`` file, fork/clone Ba contributing development test + ci installation commands/index custom diff --git a/docs/test.rst b/docs/test.rst index 8f6165600b..2923eb7af7 100644 --- a/docs/test.rst +++ b/docs/test.rst @@ -9,7 +9,7 @@ Overview The Bash-it unit tests leverage the `Bats unit test framework for Bash `_. There is no need to install Bats explicitly, the test run script will automatically download and install Bats and its dependencies. -When making changes to Bash-it, the tests are automatically executed in a test build environment on `Travis CI `_. +When making changes to Bash-it, the tests are automatically executed in a test build environment on `GitHub Actions `_. See the :ref:`Continuous Integration ` section for more details. Test Execution --------------