You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
When you’re ready to publish your code online, you can setup Continuous Integration (CI). CI is a platform that allows you to specify and run jobs or workflows that you define.
4
+
These workflows include:
5
+
6
+
- Running your test suite
7
+
- Running code checkers / linters / spellcheck
8
+
- Building your documentation
9
+
- Deploying your documentation to GitHub pages
10
+
11
+
CI also allows you to automate running workflows across a suite of environments including:
12
+
13
+
- environments containing different Python versions and
14
+
- different operating systems (Mac, Linux, Unix).
15
+
16
+
### What is Continuous Deployment (CD)?
17
+
18
+
Continuous deployment (CD) extends the CI process by automating the deployment of code changes to production or staging environments. In the case of your open source tool, CD can be used to:
19
+
20
+
- Automate publishing to PyPI
21
+
- Automate publishing your documentation to github pages or Read the Docs.
22
+
23
+
It is also used once your conda-forge recipe is set up to keep your package up to date on conda-forge.
24
+
25
+
### Why Use CI
26
+
27
+
CI can be configured to run a workflow on every commit pushed to GitHub and every pull request opened. This ensures that any changes made to your package are tested across environments before they are merged into the main branch of your code.
28
+
29
+
These checks are particularly useful if someone new is contributing to your code. Every change a contributor makes will be tested when it’s pushed to your code repository.
30
+
31
+
Together, CI and CD streamline the process of building, testing, and deploying code. They aim to improve the efficiency, quality, and reliability of software development and publication.
32
+
33
+
```{note}
34
+
All pyOpenSci packages must use some form of continuous integration. Even if you are not planning to go through peer review, we strongly recommend that you use continuous integration too!
35
+
```
36
+
37
+
In the case of GitHub actions (which we will focus on here), CI workflows are running on online servers that support GitHub.
38
+
39
+
## CI / CD Platforms
40
+
41
+
There are numerous platforms available for CI/CD. Here, we will focus on GitHub Actions (GHA) which is built into GitHub. GitHub is the most commonly used platform to store scientific open source software.
42
+
43
+
:::{note}
44
+
If you are using GitLab CI/CD many of the principles described here will apply, however the workflow files may look different.
45
+
:::
46
+
47
+
### If you aren't sure, use GitHub Actions
48
+
49
+
While you are welcome to use the continuous integration platform of your choice,
50
+
we recommend Github actions because it is free-to-use and integrated tightly
51
+
into the GitHub user interface. There is also an entire store of GitHub action
52
+
templates that you can easily use and adapt to your own needs.
53
+
54
+
:::{admonition} Other platforms that you may run into
55
+
:class: info
56
+
57
+
-[Appveyor:](https://www.appveyor.com/) used to be a goto for running tests on Windows operating systems until GitHub actions evolved to support Windows. AppVeyor has evolved to support other operating systems since Microsoft acquired GitHub.
58
+
-[Travis CI:](https://www.travis-ci.com/) Used to be the most common CI platform used in our ecosystem until they dropped free support for open source.
59
+
-[CircleCI:](https://circleci.com/) You will still see some people using CircleCI for specific tasks. CircleCi can be useful for automated builds of websites and documentation allowing you to preview the changes to that website in your browser.
60
+
:::
61
+
62
+
## Embrace automation
63
+
64
+
By embracing CI/CD, you can ensure that your code runs as you expect it to across the diverse landscapes of user environments. Further you can
65
+
automate certain checks (and in some cases code fixes) including linting and code style. You can even automate spell checking your documentation
Code coverage is the amount of your package's codebase that is run as a part of running your project's tests. A good rule of thumb is to ensure that every line of your code is run at least once during testing. However, note that good code coverage does not guarantee that your package is well-tested. For example, you may run all of your lines of code, but not account for many edge-cases that users may have. Ultimately, you should think carefully about the way your package will be used, and decide whether your tests adequately cover all of that usage.
4
+
5
+
A common service for analyzing code coverage is [codecov.io](https://codecov.io/). This project is free for open source tools, and will provide dashboards that tell you how much of your codebase is covered during your tests. We recommend setting up an account, and using codecov to keep track of your code coverage.
6
+
7
+
```{figure} ../images/code-cov-stravalib.png
8
+
:height: 450px
9
+
:alt: Screenshot of the code cov service - showing test coverage for the stravalib package. in this image you can see a list of package modules and the associated number of lines and % lines covered by tests. at the top of the image you can see what branch is being evaluated and the path to the repository being shown.
10
+
11
+
the Code cov platform is a useful tool if you wish to visually track code coverage. Using it you can not only get the same summary information that you can get with **pytest-cov** extension. You can also get a visual representation of what lines are covered by your tests and what lines are not covered. Code cove is mostly useful for evaluating unit tests and/or how much of your package code is "covered. It however will not evaluate things like integration tests and end-to-end workflows. b
0 commit comments