RFC(?): Some documentation related to contributing to clang-format

I recently saw this StackOverflow.com question about efficiently running tests for clang-format, which reminded me that clang-format has essentially nothing as written record for documentation from the perspective of someone working on the tool.

Running tests comes to mind first, since it is something I also struggled to figure out when first starting out contributing. Especially as someone with a poor setup, since compilation times lead to development downtime, running the tests in the most efficient possible way was very important to me.

There are more thing that could be there too, for example: We now have super neat Herald rules on Phabricator that point out potential flaws, but despite their convenience, I feel like they should be documented someone, both as a formality, and so they could be seen before actually making a patch.

My brief contribution to clang-tidy also reminds me that it has a great documentation page for contributing, which shows prior precedent.

Circling back to that original Stack Overflow question, I answered it to the best of my ability, how I figured out a way to run the tests as I started out, but I wanted to make this post for another reason too:
@owenpan, @mydeveloperday, @HazardyKnusperkeks, as the people I most look to for reviews, I wanted to ask your method for doing this, because maybe there really is a better way that should then be documented somewhere as the way to do it.

3 Likes

I actually just load the CMakeLists.txt with my QtCreator and choose just to build and run the FormatTests target. When working on something I use the gtest_filter also mentioned in the comment on your answer and just after getting my new tests to pass, I run everything to see if I broke anything.

FWIW, I think adding this kind of documentation is a fantastic idea. It’s also a good place to add policy decisions like how to handle formatting options that can potentially break code and other clang-format-specific policies.

1 Like

I run ninja FormatTests (and/or ninja clang-format) followed by tools/clang/unittests/Format/FormatTests (first with the --gtest_filter flag and then without the flag like what @HazardyKnusperkeks does).

I’m the same, ninja Format Tests but I put a private Makefile in the ninja directory, so I can run everything or a sub-sample of tests

all: both csharp

both:
        ninja clang-format FormatTests

test:
        ./FormatTests

namespace: all
        ./FormatTests --gtest_filter=*Name*

csharp: all
        ./FormatTests --gtest_filter=*Sharp*

javascript: all
        ./FormatTests --gtest_filter=*TestJS*

disable: all
        ./FormatTests --gtest_filter=*Spaces*

qual: all
        ./FormatTests --gtest_filter=*Qual*