From abcf9304b97704e31a87fafab637b542b7115e6d Mon Sep 17 00:00:00 2001 From: bbartels <bbartels@iastate.edu> Date: Fri, 7 Apr 2017 11:28:10 -0500 Subject: [PATCH] documentation: add CI FAQ --- documentation/ci_faq.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 documentation/ci_faq.md diff --git a/documentation/ci_faq.md b/documentation/ci_faq.md new file mode 100644 index 000000000..679e0b9f4 --- /dev/null +++ b/documentation/ci_faq.md @@ -0,0 +1,40 @@ +# Continuous Integration (CI) FAQ + +## Why did my commit fail CI? +On every commit, a script runs that performs a number of things, including +compiling code and running unit and functional tests. Whatever you did +apparently broke one of these things. + +## Why should I care about the CI results? +CI _immensely_ streamlines the development cycle by helping us catch bugs +immediately, allowing us to fix them early before they plague us (or future +users of the code base). It's a common industry practice. If you break the CI +pipeline, don't ignore it! Try your best to get the branch back in working +condition. + +## Okay, so my commit failed CI, and I guess I care. What should I do? +1. Re-run the build. + - Sometimes something weird happens, so it's good to check this. +2. Figure out what you did wrong and fix it. + - If you click on the build, you should be able to see the exact logs the + build process. Debug the error to figure out what went wrong. Maybe you + failed a test. You may need to open the source code for the test to see + where you failed, which is very insightful into figuring out what went + wrong. +3. Figure out what CI is doing wrong. + - Sometimes a test might be poorly designed. At this point, it can be really + tempting to just ignore the build failure altogether (don't do that!), or + just remove the broken test (not as bad, but still don't do that). The best + thing is to fix the test so that we continue to have good regression + test coverage over our code. + +## How does CI work? +When a commit is added to a branch in our repository, a notification is sent out +to our gitlab-ci-runner, which instructs it to checkout the updated branch and +run the directive in `.gitlab-ci.yml`. It then runs each directive, which is +made up of bash scripts to execute. In our case, we run two scripts, +`ci-build.sh` and `ci-test.sh`, which compile projects and run checks, +respectively. (Look at these scripts to learn more about how they work). If +some error occurs during the script (perhaps a forced error generated by a +failed test), then the runner sends a message back to Gitlab indicating that the +CI failed. Otherwise, it succeeds. -- GitLab