Introduction

Syzygy is all about taking apart perfectly good executable binaries, mutating them in interesting ways, and then outputting new, perfectly good executable binaries. The output binaries are either functionally equivalent, but improved in some way - like e.g. in an improved order, or else contain new functionality, which is the case for instrumented binaries.

This is pretty exacting business, so correctness and quality are very important for Syzygy, hence these policies.

Details

Contribution

If you don't work for Google and want to contribute code to Syzygy, you'll need to sign the individual or the corporate contributor license.

Check out and install the depot_tools package. This contains the custom tools necessary to check out and build Syzygy.

If you're a Google employee you don't have to install the Visual Studio toolchain to build, you just need to follow the Chromium instructions to get the toolchain automatically. You can still install the Visual Studio IDE if you want to use it for developing (but the compilation will still be done with the automatically installed toolchain).

If you don't work for Google then you'll need to manually install Visual Studio 2013 Update 5, the community edition is enough.

Once this is done, you can fetch the sources by doing:

> mkdir Syzygy
> cd Syzygy
> fetch syzygy

After this completes, you can now build with ninja (e.g. run 'ninja -C out\Release All' from the src/ directory to compile the whole project). Note that if you want to use Visual Studio as your IDE you'll need to edit your syzygy.gyp_env file, or simply set 'GYP_GENERATORS=ninja,msvs-ninja', after running 'gclient runhooks' you'll get a main solution file at src\syzygy\syzygy.sln.

Coding Guidelines

1. Your code must conform to the Chromium style guidelines, and more generally to the Google C++ and Python style guides: * https://www.chromium.org/developers/coding-style * https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml * https://google-styleguide.googlecode.com/svn/trunk/pyguide.html
2. When in doubt follow the convention in use in a particular file or elsewhere in the repository.
3. Your code should be tested by unit tests, and integration tests when appropriate. The Syzygy codebase is rigorously tested and observes strict coverage and testing standards. The continuous builder and integration tester is visible here:

https://build.chromium.org/p/client.syzygy/waterfall

1. If you are contributing for the first time please take a moment to add your name to the AUTHORS.txt file in the root of the repository.
2. All pre-submit checks must pass before committing the change. When uploading a CL these checks will be run automatically, and further directions provided. For more details see review
3. All new code must be unittested. See the testing section for details.

New submissions will trigger the continuous builder on Syzygy's buildbot, which will compile the new contribution, run a suite of tests on it, and generate a code coverage report. Build or test failures on the buildbot should be fixed immediately, either by reverting the change, or by submitting a fix as soon as possible.

Testing

Syzygy requires all C++ code to have better than 60% unittest coverage, as measured by the Syzygy coverage builder. After every submission, look at the next coverage report (you should get an email when it completes). If the new code does not meet the coverage requirement, either revert the change, or submit a fix to improve the unittest coverage.

Any submission with a non-trivial bugfix must add a regression test for the bug.

Any significant feature addition must additionally be tested by an integration test, that tests the feature end-to-end.

Review

Before being accepted into the codebase your contribution must be uploaded to the Rietveld code review website at codereview.chromium.org, and reviewed by a member of the Syzygy team. Try to find an appropriate reviewer by looking at the most recent activity in that part of the repository. If in doubt contact the team mailing list at [email protected].

Uploads to the review site are performed using "git cl upload" from the branch containing your patch.

When your patch is accepted it will receive a "Looks good to me" (LGTM) from one or more of your reviewers. At this point it is ready to commit.

Commit

If this a one-off contribution it is easiest for a full-time team member to land the CL for you. You will receive attribution in the commit message and the AUTHORS.txt file.

If you have made or plan to make multiple contributions you will be added as a contributor and provided with access to the repository. In this case you will land your CL using "git cl land".

Release criteria

TODO(siggi): release criteria.