Skip to content

Latest commit

 

History

History
225 lines (171 loc) · 7.51 KB

contributing.rst

File metadata and controls

225 lines (171 loc) · 7.51 KB
Raw

Contributing to cmake-format

General Rules

  1. Please use pylint and flake8 to check your code for lint. There are config files in the repo.
  2. There is a python unittest suite in cmakelangtests.py. Run with python -Bm cmakelang.tests (ensure modified code is on the python path). Alternatively you can use cmake (make test, ninja test, etc) or bazel (bazel test ...).
  3. There's an autopep8 config file in the repo as well. Feel free to use that to format the code. Note that autopep8 and pylint disagree in a few places so using autopep8 may require some manual edits afterward.

Build Systems

You don't need to "build" cmake-format, but there are cmake and bazel build rules that you can use if you find it convenient. For the most part your contribution is in good shape if the test and lint (cmake) build targets pass or, equivalently, if bazel test ... passes. If you add new files to the repository, please update the corresponding CMakeLists.txt and BUILD files to keep the lint and test configurations up to date.

Sidecar Tests

Whether or not to write your tests in cmake or in python will depend largely on the test. If you simply want to assert that a particular snippet of code is formatted in a specific way, writing the test in cmake is most natural. If any logic is needed, then writing in the body of a python function makes the most sense.

Test written in cmake are stored in .cmake sidecar files associated with python unittest cases (see command_tests/*).

The format of these tests are very simple. The test begins with a line comment in the form of:

# test: <test-name>

And ends with the start of the next test, the end of the file, or a line comment in the form of:

# end-test

If non-default configuration options are required, or if you would like to assert a lex, parse, or layout result, then you can specify that in an optional bracket comment immediately following the # test: sentinel. The bracket comment must begin and end on it's own line, such as:

#[=[
   line_width = 10
]=]

The content of the comment is parsed as python and variables are interpreted as configuration variables, except for the following:

  • expect_lex - a list of lexer tokens indicated the expected lex result
  • expect_parse - a tree of parse node names indicated the expected parse tree structure
  • expect_layout - a tree of layout node names and geometries indicated the expected layout result.

A test called test_<test-name> will be generated at runtime. The test will involve cmake-format formatting the code snippet using the default configuration, and asserting that the output matches the input.

Debugging

Formatting

For the most part, cmake-format ignores white-space when it parses the list file into the parse tree so most of the formatting tests can be restricted to "idempotency" tests. In other words, you write down the listfile code in the format you expect and if cmake-format doesn't change it, the test passes.

Lexing, Parsing, Layout

If you suspect a problem with the lexing, parsing, or layout algorithms, try to create a minimial working example of the problem, and use the --dump [lex|parse|layout] command line option to inspect the output of the different phases.

Once you've identified the problem, the best thing to do is create a test asserting an expected output at the problematic phase. You can start by asserting an empty output. For example, something like:

# test: debug_my_case
#[=[
  expect_lex = []
]=]
if(something)
  your_cmake_code_here(foo bar baz)
else()

The test will fail, but the error message will print out the actual result. In the example above:

Second list contains 19 additional elements.
First extra element 0:
TokenType.WORD

- []
+ [TokenType.WORD,
+  TokenType.LEFT_PAREN,
+  TokenType.WORD,
+  TokenType.RIGHT_PAREN,
+  TokenType.NEWLINE,
+  TokenType.WHITESPACE,
+  TokenType.WORD,
+  TokenType.LEFT_PAREN,
+  TokenType.WORD,
+  TokenType.WHITESPACE,
+  TokenType.WORD,
+  TokenType.WHITESPACE,
+  TokenType.WORD,
+  TokenType.RIGHT_PAREN,
+  TokenType.NEWLINE,
+  TokenType.WORD,
+  TokenType.LEFT_PAREN,
+  TokenType.RIGHT_PAREN,
+  TokenType.NEWLINE]

You can copy-paste the actual output as the expected output as a starting point for your test. You can modify the "expected" specification to match what the output should be. Then, as you iterate, you can use the test to know when you've fixed the problem.

Pull Requests

Feel free to make a pull request on github, though please take note of the following rules and guidelines. These rules are enforced through the travis CI builds so if travis passes your submission is probably in good shape.

Squash your feature

Please squash your changes when issuing a pull request so that the request is for a single commit. This helps us move the patch from the public github mirror into the upstream respository. When updating your request, please squash additional commits (you will likely need to force-push to your feature branch).

Rebase before submit

Please rebase your patch on the current HEAD before submitting the pull request. This helps us to keep a tidy history. When we merge your commit we don't want to create graph connections across long regions of the git history. Travis will fail any pull request which is more than 10 commits behind the HEAD.

Sign your commit

When making a pull request, please sign the commit (use git commit -S).

Sign the copyright assignment

Please sign the copyright assignment agreement (details below) using the same PGP key you use to sign the commit, and please ensure that the key is available on the popular keyservers. Travis will fetch it from https://keyserver.ubuntu.com

Copyright Assignment

To sign the copyright assignment agreement the quick way, run:

python -Bm cmakelang.contrib.sign_ca

from the root of the repository.

For the long way, please follow this process:

  1. Copy the file cmakelang/contrib/individual_ca.txt to some working directory as, e.g., cmake-format-ca.txt.in.

  2. Replace the template strings at the bottom with your actual name and email address.

  3. Sign the document with e.g.:

    gpg --output cmake-format-ca.txt --clearsign cmake-format-ca.txt.in``

    Please be sure to use the same pgp key that you'll be using to sign your commits.

  4. Copy the asci-armored signature packet at the bottom of the signed document and paste it into cmakelang/contrib/signature_db.json. Include this change in your first pull request.

Un-Assigned contributions

In general, copyright for contributions should be assigned to the project. This should keep everything on the level should we find the need to offer cmake-format though additional licenses in the future.

If you'd like to make a significant contribution to cmake-format but don't agree to the terms of the copyright assignment please contact us to set up an alternate agreement. Otherwise, please consider filing a feature-request for changes you would like to see implemented.