Skip to content

Latest commit

 

History

History
105 lines (73 loc) · 4.57 KB

README.format.md

File metadata and controls

105 lines (73 loc) · 4.57 KB
Raw

GPOPT and ORCA code formatting

Tools

  1. We are using clang-format.

  1. We use the current stable release, with an eye to good new options coming from the next release. As of writing we're using release 10, the configuration options are documented here.

  2. As mentioned in the style guide, the format style is based on Google C++ style guide, but mixed in with Postgres formatting rules (break before braces, 4-space tabbing, etc)

  3. We should use an explicit, complete (locked down) specification for the .clang-format file.

  4. But our intent is better expressed as well organized, commented yaml. We use a simple script to generate the complete config file from the intent file. For example, on my Linux laptop, I run:

    CLANG_FORMAT=clang-format-10 src/tools/fmt gen

    If the correct version of clang-format is installed as clang-format (as is the case in macOS), you can omit the environment variable override.

  5. To check for formatting conformance, one can run

    src/tools/fmt chk

    It will succeed quietly (with return code 0) or point out the first few places that need to be formatted.

  6. To wholesale format all of ORCA and GPOPT

    src/tools/fmt fmt

    On my laptop this takes about 2.5 seconds.

  7. Of course, when you're writing code, 2.5 seconds is an eternity. Here's a non-exhaustive list of editor / IDE plugins that provide an integrated formatting experience. The in-editor formatting typically takes around 50ms. Depending on your plugin / editor, the formatting either happens automatically as you type, on save, or when you invoke it explicitly.

    • A community VIM plugin that looks promising and claims to be better than the official VIM integration
    • Clion detects .clang-format automatically and switches to using it for the built-in "Reformat Code" and "Reformat File...".

Annotating history

  1. It's usually desirable to skip past formatting commits when doing a git blame. Fortunately, git blame has two options that are extremely helpful:
    1. -w ignore whitespace
    2. --ignore-rev / --ignore-revs-file accepts commits to skip while annotating

When combined, -w --ignore-revs-file produces a perfectly clean annotation, unencumbered by a noisy history. This also gives us a peace of mind in changing our formats more frequently without worrying about hindering the git blame experience, rather than "do it once, set it in stone, and forget about it".

Reformatting in-flight patches

ORCA is actively developed, that means when the "big bang" formatting change is merged, there will inevitably be a number of patches that were started well before the formatting change, and these patches will now need to conform to the new format. The following steps are used to convert in-flight branches to the new format.

  1. Get the format script

    git restore --source master -- src/tools/fmt

  2. Get the format configuration files

    git restore --source master -- src/include/gpopt/.clang-format src/backend/gpopt/.clang-format src/backend/gporca/.clang-format

  3. Use git filter-branch to rewrite the branch history

    git filter-branch --tree-filter 'src/tools/fmt fmt' master..

  4. Now that we have reformatted the history, rebase on top of master

    git rebase master