diff options
Diffstat (limited to 'src/third_party/zstandard/zstd/CONTRIBUTING.md')
| -rw-r--r-- | src/third_party/zstandard/zstd/CONTRIBUTING.md | 91 |
1 files changed, 38 insertions, 53 deletions
diff --git a/src/third_party/zstandard/zstd/CONTRIBUTING.md b/src/third_party/zstandard/zstd/CONTRIBUTING.md index a936d747e06..e7e545129e5 100644 --- a/src/third_party/zstandard/zstd/CONTRIBUTING.md +++ b/src/third_party/zstandard/zstd/CONTRIBUTING.md @@ -68,8 +68,8 @@ Our contribution process works in three main stages: ``` 2. Code Review and CI tests * Ensure CI tests pass: - * Before sharing anything to the community, make sure that all CI tests pass on your local fork. - See our section on setting up your CI environment for more information on how to do this. + * Before sharing anything to the community, create a pull request in your own fork against the dev branch + and make sure that all GitHub Actions CI tests pass. See the Continuous Integration section below for more information. * Ensure that static analysis passes on your development machine. See the Static Analysis section below to see how to do this. * Create a pull request: @@ -140,6 +140,42 @@ It can be useful to look at additional static analyzers once in a while (and we This is different from running a static analyzer once in a while, looking at the output, and __cherry picking__ a few warnings that seem helpful, either because they detected a genuine risk of bug, or because it helps expressing the code in a way which is more readable or more difficult to misuse. These kind of reports can be useful, and are accepted. +## Continuous Integration +CI tests run every time a pull request (PR) is created or updated. The exact tests +that get run will depend on the destination branch you specify. Some tests take +longer to run than others. Currently, our CI is set up to run a short +series of tests when creating a PR to the dev branch and a longer series of tests +when creating a PR to the release branch. You can look in the configuration files +of the respective CI platform for more information on what gets run when. + +Most people will just want to create a PR with the destination set to their local dev +branch of zstd. You can then find the status of the tests on the PR's page. You can also +re-run tests and cancel running tests from the PR page or from the respective CI's dashboard. + +Almost all of zstd's CI runs on GitHub Actions (configured at `.github/workflows`), which will automatically run on PRs to your +own fork. A small number of tests run on other services (e.g. Travis CI, Circle CI, Appveyor). +These require work to set up on your local fork, and (at least for Travis CI) cost money. +Therefore, if the PR on your local fork passes GitHub Actions, feel free to submit a PR +against the main repo. + +### Third-party CI +A small number of tests cannot run on GitHub Actions, or have yet to be migrated. +For these, we use a variety of third-party services (listed below). It is not necessary to set +these up on your fork in order to contribute to zstd; however, we do link to instructions for those +who want earlier signal. + +| Service | Purpose | Setup Links | Config Path | +|-----------|------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------| +| Travis CI | Used for testing on non-x86 architectures such as PowerPC | https://docs.travis-ci.com/user/tutorial/#to-get-started-with-travis-ci-using-github <br> https://github.com/marketplace/travis-ci | `.travis.yml` | +| AppVeyor | Used for some Windows testing (e.g. cygwin, mingw) | https://www.appveyor.com/blog/2018/10/02/github-apps-integration/ <br> https://github.com/marketplace/appveyor | `appveyor.yml` | +| Cirrus CI | Used for testing on FreeBSD | https://github.com/marketplace/cirrus-ci/ | `.cirrus.yml` | +| Circle CI | Historically was used to provide faster signal,<br/> but we may be able to migrate these to Github Actions | https://circleci.com/docs/2.0/getting-started/#setting-up-circleci <br> https://youtu.be/Js3hMUsSZ2c <br> https://circleci.com/docs/2.0/enable-checks/ | `.circleci/config.yml` | + +Note: the instructions linked above mostly cover how to set up a repository with CI from scratch. +The general idea should be the same for setting up CI on your fork of zstd, but you may have to +follow slightly different steps. In particular, please ignore any instructions related to setting up +config files (since zstd already has configs for each of these services). + ## Performance Performance is extremely important for zstd and we only merge pull requests whose performance landscape and corresponding trade-offs have been adequately analyzed, reproduced, and presented. @@ -339,57 +375,6 @@ counter `L1-dcache-load-misses` TODO - -## Setting up continuous integration (CI) on your fork -Zstd uses a number of different continuous integration (CI) tools to ensure that new changes -are well tested before they make it to an official release. Specifically, we use the platforms -travis-ci, circle-ci, and appveyor. - -Changes cannot be merged into the main dev branch unless they pass all of our CI tests. -The easiest way to run these CI tests on your own before submitting a PR to our dev branch -is to configure your personal fork of zstd with each of the CI platforms. Below, you'll find -instructions for doing this. - -### travis-ci -Follow these steps to link travis-ci with your github fork of zstd - -1. Make sure you are logged into your github account -2. Go to https://travis-ci.org/ -3. Click 'Sign in with Github' on the top right -4. Click 'Authorize travis-ci' -5. Click 'Activate all repositories using Github Apps' -6. Select 'Only select repositories' and select your fork of zstd from the drop down -7. Click 'Approve and Install' -8. Click 'Sign in with Github' again. This time, it will be for travis-pro (which will let you view your tests on the web dashboard) -9. Click 'Authorize travis-pro' -10. You should have travis set up on your fork now. - -### circle-ci -TODO - -### appveyor -Follow these steps to link circle-ci with your github fork of zstd - -1. Make sure you are logged into your github account -2. Go to https://www.appveyor.com/ -3. Click 'Sign in' on the top right -4. Select 'Github' on the left panel -5. Click 'Authorize appveyor' -6. You might be asked to select which repositories you want to give appveyor permission to. Select your fork of zstd if you're prompted -7. You should have appveyor set up on your fork now. - -### General notes on CI -CI tests run every time a pull request (PR) is created or updated. The exact tests -that get run will depend on the destination branch you specify. Some tests take -longer to run than others. Currently, our CI is set up to run a short -series of tests when creating a PR to the dev branch and a longer series of tests -when creating a PR to the release branch. You can look in the configuration files -of the respective CI platform for more information on what gets run when. - -Most people will just want to create a PR with the destination set to their local dev -branch of zstd. You can then find the status of the tests on the PR's page. You can also -re-run tests and cancel running tests from the PR page or from the respective CI's dashboard. - ## Issues We use GitHub issues to track public bugs. Please ensure your description is clear and has sufficient instructions to be able to reproduce the issue. |