Skip to content
Snippets Groups Projects
Normal view Permalink
ci_faq.md 2.43 KiB
Newer Older
bbartels's avatar
documentation: add CI FAQ
bbartels committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 
# 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.
bbartels's avatar
Update ci_faq.md  
bbartels committed
19 
   - If you click on the build, you should be able to see the exact logs of the
bbartels's avatar
documentation: add CI FAQ
bbartels committed
20 21 22 23 24 25 26 27 28 29 30 
     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.
bbartels's avatar
Update ci_faq.md  
bbartels committed
31 32 33 34 35 
## My build failed due to unavailable software. How do I install things on CI?
Each build is run within a docker image. Add whatever software you need on the
`sudo apt install ...` line inside of the `.gitlab-ci.yml` file in the root
directory.
bbartels's avatar
documentation: add CI FAQ
bbartels committed
36 37 38 
## 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
Peter Thedens's avatar
Update ci_faq.md  
Peter Thedens committed
39 
run the directive in [`.gitlab-ci.yml`](.gitlab-ci.yml). It then runs each directive, which is
bbartels's avatar
documentation: add CI FAQ
bbartels committed
40 
made up of bash scripts to execute. In our case, we run two scripts,
Peter Thedens's avatar
Update ci_faq.md  
Peter Thedens committed
41 42 43 44 45 
[`ci-build.sh`](ci/ci-build.sh) and [`ci-test.sh`](ci/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.