From 76c52b6b7c2c3b3343980dc53db256693188793d Mon Sep 17 00:00:00 2001 From: Bimba Shrestha Date: Sun, 16 Feb 2020 11:31:17 -0500 Subject: [PATCH 1/3] Adding steps for setting up travis and appveyor (and some general notes) --- CONTRIBUTING.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dd013f808..d8d0bc487 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,6 +26,56 @@ to do this once to work on any of Facebook's open source projects. Complete your CLA here: +## 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 girhub 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 master 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. @@ -34,7 +84,7 @@ Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe disclosure of security bugs. In those cases, please go through the process outlined on that page and do not file a public issue. -## Coding Style +## Coding Style * 4 spaces for indentation rather than tabs ## License From 042b28bd2c1b4c0e76f6c97ec9661324fd7b72b2 Mon Sep 17 00:00:00 2001 From: Bimba Shrestha Date: Tue, 18 Feb 2020 13:03:52 -0800 Subject: [PATCH 2/3] Outlining our current workflow --- CONTRIBUTING.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d8d0bc487..e72ec9270 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,6 +26,89 @@ to do this once to work on any of Facebook's open source projects. Complete your CLA here: +## Workflow +Zstd uses a branch-based workflow for making changes to the codebase. Typically, zstd +will use a new branch per sizable topic. For smaller changes, it is okay to lump multiple +related changes into a branch. + +Our contribution process works in three main stages: +1. Local development + * Update: + * Checkout your fork of zstd if you have not already + ``` + git checkout https://github.com//zstd + cd zstd + ``` + * Update your local dev branch + ``` + git pull https://github.com/facebook/zstd dev + git push origin dev + ``` + * Topic and deveopment: + * Make a new branch on your fork about the topic you're developing for + ``` + # branch names should be consise but sufficiently informative + git checkout -b + git push origin + ``` + * Make commits and push + ``` + # make some changes = + git add -u && git commit -m + git push origin + ``` + * Note: run local tests to ensure that your changes didn't break existing functionality + * Quick check + ``` + make shortest + ``` + * Longer check + ``` + make test + ``` +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. + * Create a pull request: + * When you are ready to share you changes to the community, create a pull request from your branch + to facebook:dev. You can do this very easily by clicking 'Create Pull Request' on your fork's home + page. + * From there, select the branch where you made changes as your source branch and facebook:dev + as the destination. + * Examine the diff presented between the two branches to make sure there is nothing unexpected. + * Write a good pull request description: + * While there is no strict template that our contributers follow, we would like them to + sufficiently summarize and motivate the changes they are proposing. We recommend all pull requests, + at least indirectly, address the following points. + * Is this pull request important and why? + * Is it addressing an issue? If so, what issue? (provide links for convenience please) + * Is this a new feature? If so, why is it useful and/or necessary? + * Are there background references and documents that reviewers should be aware of to properly assess this change? + * Note: make sure to point out any design and architectural decisions that you made and the rationale behind them. + * Note: if you have been working with a specific user and would like them to review your work, make sure you mention them using (@) + * Submit the pull request and iterate with feedback. +3. Merge and Release + * Getting approval: + * You will have to iterate on your changes with feedback from other collaborators to reach a point + where your pull request can be safely merged. + * To avoid too many comments on style and convention, make sure that you have a + look at your style section below before creating a pull request. + * Eventually, someone from the zstd team will approve your pull request and not long after merge it into + the dev branch. + * Housekeeping: + * Most PRs are linked with one or more Github issues. If this is the case for your PR, make sure + the corresponding issue is mentioned. If your change 'fixes' or completely addresses the + issue at hand, then please indicate this by requesting that an issue be closed by commenting. + * Just because your changes have been merged does not mean the topic or larger issue is complete. Remember + that the change must make it to an official zstd release for it to be meaningful. We recommend + that contributers track the activity on their pull request and corresponding issue(s) page(s) until + their change makes it to the next release of zstd. Users will often discover bugs in your code or + suggest ways to refine and improve your initial changes even after the pull request is merged. + +## Zstandard style and conventions + + ## 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 From 8f8c53d995583600886957e1942f388360bd808f Mon Sep 17 00:00:00 2001 From: Bimba Shrestha Date: Tue, 18 Feb 2020 14:21:19 -0800 Subject: [PATCH 3/3] Remove redundant section and typo --- CONTRIBUTING.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e72ec9270..02834659c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -93,7 +93,7 @@ Our contribution process works in three main stages: * You will have to iterate on your changes with feedback from other collaborators to reach a point where your pull request can be safely merged. * To avoid too many comments on style and convention, make sure that you have a - look at your style section below before creating a pull request. + look at our style section below before creating a pull request. * Eventually, someone from the zstd team will approve your pull request and not long after merge it into the dev branch. * Housekeeping: @@ -106,9 +106,6 @@ Our contribution process works in three main stages: their change makes it to the next release of zstd. Users will often discover bugs in your code or suggest ways to refine and improve your initial changes even after the pull request is merged. -## Zstandard style and conventions - - ## 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