Thursday, November 28, 2019

How not to build code when only docs are changed (AppVeyor)

Having documentation and code in separate repositories makes sense for many projects but not for all.

When you make changes to code you want the CI process to build the code to make sure everything is ok with it. Then, once someone (or rather something) other than you have verified it's ok, it can be merged/committed.

That's all good but sometimes it can be very time-consuming.

When making a small change you can easily get frustrated if you haven't changed anything related to code.
I only fixed a typo on the readme. Why is it doing a full build?
In scenarios like this, you shouldn't be building all the code.

There are lots of reasons not to build the code but the most important is that it prevents quick, simple things from being quick and simple. The consequence of this is that if something should be quick and simple isn't people are less likely to do it (again).

I'm less likely to submit a fix for an issue in your docs if it takes hours. And yes, I count the time all the actions on the PR will take.

Fortunately, it's really simple to avoid this issue. Just configure your server to not build the code when only docs have been changed.

For my projects (built on AppVeyor) I use the following configuration to avoid building code when the only things that have changed are images (kept in the 'art directory'), anything related to docs, and/or any markdown files.

Here's the relevant snippet from my `appveyor.yml` file.

    - art/*
    - docs/*
    - '**/*.md'

I'm sure there's a similar way to do this with whatever build system/server/CI/CD process you use too.

None of those things are related to the code and so there's no need to rebuild the code to look for any accidental breaking changes or failing tests.

Log entry showing build being skipped because of the file types changed

The next thing I'd like to do with my current process is to add additional checks for documentation and validate those checks only when the affected docs are changed. But that's a task for another day...


Post a Comment