"Fossies" - the Fresh Open Source Software Archive

Member "zstd-1.4.5/CONTRIBUTING.md" (22 May 2020, 22520 Bytes) of package /linux/misc/zstd-1.4.5.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the latest Fossies "Diffs" side-by-side code changes report for "CONTRIBUTING.md": 1.4.4_vs_1.4.5.

Contributing to Zstandard

We want to make contributing to this project as easy and transparent as possible.

Our Development Process

New versions are being developed in the "dev" branch, or in their own feature branch. When they are deemed ready for a release, they are merged into "master".

As a consequences, all contributions must stage first through "dev" or their own feature branch.

Pull Requests

We actively welcome your pull requests.

  1. Fork the repo and create your branch from dev.
  2. If you've added code that should be tested, add tests.
  3. If you've changed APIs, update the documentation.
  4. Ensure the test suite passes.
  5. Make sure your code lints.
  6. If you haven't already, complete the Contributor License Agreement ("CLA").

Contributor License Agreement ("CLA")

In order to accept your pull request, we need you to submit a CLA. You only need to do this once to work on any of Facebook's open source projects.

Complete your CLA here: https://code.facebook.com/cla

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
  2. Code Review and CI tests
  3. Merge and Release

Static Analysis

Static analysis is a process for examining the correctness or validity of a program without actually executing it. It usually helps us find many simple bugs. Zstd uses clang's scan-build tool for static analysis. You can install it by following the instructions for your OS on https://clang-analyzer.llvm.org/scan-build.

Once installed, you can ensure that our static analysis tests pass on your local development machine by running:

make staticAnalyze

In general, you can use scan-build to static analyze any build script. For example, to static analyze just contrib/largeNbDicts and nothing else, you can run:

scan-build make -C contrib/largeNbDicts largeNbDicts

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. This high bar for performance means that every PR which has the potential to impact performance takes a very long time for us to properly review. That being said, we always welcome contributions to improve performance (or worsen performance for the trade-off of something else). Please keep the following in mind before submitting a performance related PR:

  1. Zstd isn't as old as gzip but it has been around for time now and its evolution is very well documented via past Github issues and pull requests. It may be the case that your particular performance optimization has already been considered in the past. Please take some time to search through old issues and pull requests using keywords specific to your would-be PR. Of course, just because a topic has already been discussed (and perhaps rejected on some grounds) in the past, doesn't mean it isn't worth bringing up again. But even in that case, it will be helpful for you to have context from that topic's history before contributing.
  2. The distinction between noise and actual performance gains can unfortunately be very subtle especially when microbenchmarking extremely small wins or losses. The only remedy to getting something subtle merged is extensive benchmarking. You will be doing us a great favor if you take the time to run extensive, long-duration, and potentially cross-(os, platform, process, etc) benchmarks on your end before submitting a PR. Of course, you will not be able to benchmark your changes on every single processor and os out there (and neither will we) but do that best you can:) We've adding some things to think about when benchmarking below in the Benchmarking Performance section which might be helpful for you.
  3. Optimizing performance for a certain OS, processor vendor, compiler, or network system is a perfectly legitimate thing to do as long as it does not harm the overall performance health of Zstd. This is a hard balance to strike but please keep in mind other aspects of Zstd when submitting changes that are clang-specific, windows-specific, etc.

Benchmarking Performance

Performance microbenchmarking is a tricky subject but also essential for Zstd. We value empirical testing over theoretical speculation. This guide it not perfect but for most scenarios, it is a good place to start.

Stability

Unfortunately, the most important aspect in being able to benchmark reliably is to have a stable benchmarking machine. A virtual machine, a machine with shared resources, or your laptop will typically not be stable enough to obtain reliable benchmark results. If you can get your hands on a desktop, this is usually a better scenario.

Of course, benchmarking can be done on non-hyper-stable machines as well. You will just have to do a little more work to ensure that you are in fact measuring the changes you've made not and noise. Here are some things you can do to make your benchmarks more stable:

  1. The most simple thing you can do to drastically improve the stability of your benchmark is to run it multiple times and then aggregate the results of those runs. As a general rule of thumb, the smaller the change you are trying to measure, the more samples of benchmark runs you will have to aggregate over to get reliable results. Here are some additional things to keep in mind when running multiple trials:
  2. You cannot really get reliable benchmarks if your host machine is simultaneously running another cpu/memory-intensive application in the background. If you are running benchmarks on your personal laptop for instance, you should close all applications (including your code editor and browser) before running your benchmarks. You might also have invisible background applications running. You can see what these are by looking at either Activity Monitor on Mac or Task Manager on Windows. You will get more stable benchmark results of you end those processes as well.
  3. To benchmark, you will likely end up writing a separate c/c++ program that will link libzstd. Dynamically linking your library will introduce some added variation (not a large amount but definitely some). Statically linking libzstd will be more stable. Static libraries should be enabled by default when building zstd.
  4. Use a profiler with a good high resolution timer. See the section below on profiling for details on this.
  5. Disable frequency scaling, turbo boost and address space randomization (this will vary by OS)
  6. Try to avoid storage. On some systems you can use tmpfs. Putting the program, inputs and outputs on tmpfs avoids touching a real storage system, which can have a pretty big variability.

Also check our LLVM's guide on benchmarking here: https://llvm.org/docs/Benchmarking.html

Zstd benchmark

The fastest signal you can get regarding your performance changes is via the in-build zstd cli bench option. You can run Zstd as you typically would for your scenario using some set of options and then additionally also specify the -b# option. Doing this will run our benchmarking pipeline for that options you have just provided. If you want to look at the internals of how this benchmarking script works, you can check out programs/benchzstd.c

For example: say you have made a change that you believe improves the speed of zstd level 1. The very first thing you should use to asses whether you actually achieved any sort of improvement is zstd -b. You might try to do something like this. Note: you can use the -i option to specify a running time for your benchmark in seconds (default is 3 seconds). Usually, the longer the running time, the more stable your results will be.

$ git checkout <commit-before-your-change>
$ make && cp zstd zstd-old
$ git checkout <commit-after-your-change>
$ make && cp zstd zstd-new
$ zstd-old -i5 -b1 <your-test-data>
 1<your-test-data>         :      8990 ->      3992 (2.252), 302.6 MB/s , 626.4 MB/s
$ zstd-new -i5 -b1 <your-test-data>
 1<your-test-data>         :      8990 ->      3992 (2.252), 302.8 MB/s , 628.4 MB/s

Unless your performance win is large enough to be visible despite the intrinsic noise on your computer, benchzstd alone will likely not be enough to validate the impact of your changes. For example, the results of the example above indicate that effectively nothing changed but there could be a small <3% improvement that the noise on the host machine obscured. So unless you see a large performance win (10-15% consistently) using just this method of evaluation will not be sufficient.

Profiling

There are a number of great profilers out there. We're going to briefly mention how you can profile your code using instruments on mac, perf on linux and visual studio profiler on windows.

Say you have an idea for a change that you think will provide some good performance gains for level 1 compression on Zstd. Typically this means, you have identified a section of code that you think can be made to run faster.

The first thing you will want to do is make sure that the piece of code is actually taking up a notable amount of time to run. It is usually not worth optimzing something which accounts for less than 0.0001% of the total running time. Luckily, there are tools to help with this. Profilers will let you see how much time your code spends inside a particular function. If your target code snippit is only part of a function, it might be worth trying to isolate that snippit by moving it to its own function (this is usually not necessary but might be).

Most profilers (including the profilers dicusssed below) will generate a call graph of functions for you. Your goal will be to find your function of interest in this call grapch and then inspect the time spent inside of it. You might also want to to look at the annotated assembly which most profilers will provide you with.

Instruments

We will once again consider the scenario where you think you've identified a piece of code whose performance can be improved upon. Follow these steps to profile your code using Instruments.

  1. Open Instruments
  2. Select Time Profiler from the list of standard templates
  3. Close all other applications except for your instruments window and your terminal
  4. Run your benchmarking script from your terminal window
$ zstd -b1 -i5 <my-data> # this will run for 5 seconds
  1. Once you run your benchmarking script, switch back over to instruments and attach your process to the time profiler. You can do this by:
  2. You profiler will now start collecting metrics from your bencharking script. Once you think you have collected enough samples (usually this is the case after 3 seconds of recording), stop your profiler.
  3. Make sure that in toolbar of the bottom window, profile is selected.
  4. You should be able to see your call graph.
  5. Dig down the graph to find your function call and then inspect it by double clicking the list item. You will be able to see the annotated source code and the assembly side by side.

Perf

This wiki has a pretty detailed tutorial on getting started working with perf so we'll leave you to check that out of you're getting started:

https://perf.wiki.kernel.org/index.php/Tutorial

Some general notes on perf:

Visual Studio

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 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.

Facebook has a bounty program 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

License

By contributing to Zstandard, you agree that your contributions will be licensed under both the LICENSE file and the COPYING file in the root directory of this source tree.