Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
A semi-complete overview of Swimm and CI tools as it stands now.

Continuous Integration

We highly recommend that you incorporate continuous integration into your workflow if you haven't yet, and make Swimm a part of that integration. Once you do that, you'll have continuous documentation.

Our CLI tools can inform your build process of:

  • Documentation being out-of-sync
  • Documentation coverage falling below a configurable, defined value expressed as a score between 0.00 and 100.00.

Your build process can then decide what to do - block the build? open issues and set a due date? It's up to your team to decide what works best, but the debt won't just slide by quietly anymore.

Swimm also supports pre-commit hooks that run in your local repository when they're triggered by a commit. The pre-commit hooks are identical in functionality to the continuous integration hooks, the difference is they run only on your machine.

Examples for Github Actions, Bitbucket Pipelines, Travis and Husky can be found within the "Integrations" menu up top which is visible when you have any repository selected.

pre-commit

Pre-commit works with Git to intercept certain kinds of events through the use of hooks, which allows actions to run before the commit transaction actually takes place. Swimm's CI tools are just as useful if run pre-commit as they are if run through a CI server - the main difference is the check runs on your local machine before the commit actually takes place, and not as a part of the push / PR / review cycle.

The result is the same, failed documentation checks can trigger other things to happen, or even block the commit, depending on the conventions that feel right for you and your team.

To install pre-commit hooks, first install pre-commit, and then follow the instructions in this repository.

Other CI / Build Servers / Test Servers

If you'd like us to support another kind of system, please let us know! In most cases, we can have a usable integration ready in a week or less.

If you need to integrate Swimm into a custom system, or need to get something up and running on a system we don't yet support right away, here are some things to keep in mind:

Verifying Docs As Up-To-Date

swimm verify Is the command to run in order to see if documentation is up to date. If not, it will tell you which modules need attention, and exit with a nonzero status.

If you need to run the test 'headless' on a build server, you can use the following command to pull in the latest client and have node.js (10.15.0+) execute it:

echo "Verifying documentation units"
src=$(curl -s https://api.github.com/repos/swimmio/SwimmReleases/releases/latest | grep 'browser_download_url.*swimm-cli' | cut -d '"' -f 4) 
wget -O swimm_cli $src
node swimm_cli --version  
node swimm_cli verify

Verify Overall Coverage

swimm coverage Will scan whatever code Git knows about and compare that to the amount of documentation you've created. The result will be a score of 0 to 100. To get that number, try the following command:

swimm coverage | grep "/" | awk '{print $4}'

Expect a float (as in 0.00 or 89.73). If you need a whole number (0 - 100), run this instead:

swimm coverage | grep "/" | awk '{print $4}' | cut -d. -f1

Again, if you need to run headless on a build server that we don't currently have integration for, use the same method we used above for verify, except run coverage instead.

If you get stuck or just want to show us what you came up with, please reach out!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment