@llvm/pr-subscribers-clang-tools-extra

Author: Mohamed Emad (hulxv)

diff --git a/clang-tools-extra/include-cleaner/test/tool.cpp b/clang-tools-extra/include-cleaner/test/tool.cpp
index d72d2317ce2b1..8b723a5bf40e2 100644
--- a/clang-tools-extra/include-cleaner/test/tool.cpp
+++ b/clang-tools-extra/include-cleaner/test/tool.cpp
@@ -6,11 +6,11 @@ int x = foo();
 //      CHANGE: - "foobar.h"
 // CHANGE-NEXT: + "foo.h"
 
-//         RUN: clang-include-cleaner -remove=0 -print=changes %s -- -I%S/Inputs/ | FileCheck --check-prefix=INSERT %s
+//         RUN: clang-include-cleaner -disable-remove -print=changes %s -- -I%S/Inputs/ | FileCheck --check-prefix=INSERT %s
 //  INSERT-NOT: - "foobar.h"
 //      INSERT: + "foo.h"
 
-//         RUN: clang-include-cleaner -insert=0 -print=changes %s -- -I%S/Inputs/ | FileCheck --check-prefix=REMOVE %s
+//         RUN: clang-include-cleaner -disable-insert -print=changes %s -- -I%S/Inputs/ | FileCheck --check-prefix=REMOVE %s
 //      REMOVE: - "foobar.h"
 //  REMOVE-NOT: + "foo.h"
 
diff --git a/clang-tools-extra/include-cleaner/tool/IncludeCleaner.cpp b/clang-tools-extra/include-cleaner/tool/IncludeCleaner.cpp
index 1d9458ffc4d32..472611073f732 100644
--- a/clang-tools-extra/include-cleaner/tool/IncludeCleaner.cpp
+++ b/clang-tools-extra/include-cleaner/tool/IncludeCleaner.cpp
@@ -91,16 +91,16 @@ cl::opt<bool> Edit{
     cl::cat(IncludeCleaner),
 };
 
-cl::opt<bool> Insert{
-    "insert",
-    cl::desc("Allow header insertions"),
-    cl::init(true),
+cl::opt<bool> DisableInsert{
+    "disable-insert",
+    cl::desc("DIsable header insertions"),
+    cl::init(false),
     cl::cat(IncludeCleaner),
 };
-cl::opt<bool> Remove{
-    "remove",
-    cl::desc("Allow header removals"),
-    cl::init(true),
+cl::opt<bool> DisableRemove{
+    "disable-remove",
+    cl::desc("Disable header removals"),
+    cl::init(false),
     cl::cat(IncludeCleaner),
 };
 
@@ -183,9 +183,9 @@ class Action : public clang::ASTFrontendAction {
     auto Results =
         analyze(AST.Roots, PP.MacroReferences, PP.Includes, &PI,
                 getCompilerInstance().getPreprocessor(), HeaderFilter);
-    if (!Insert)
+    if (DisableInsert)
       Results.Missing.clear();
-    if (!Remove)
+    if (DisableRemove)
       Results.Unused.clear();
     std::string Final = fixIncludes(Results, AbsPath, Code, getStyle(AbsPath));
 

@AaronBallman @hokein can you please review this PR? It has been opened for a long time without any review

Do we need a deprecation period for this change? This will break anyone using the old names in scripts and whatnot.

Also, the changes will need something in the release notes so users know about the new names.

Is there a specific way to mark flags as deprecated? I didn't find anything like that in Support/CommandLine. It will be useful if we implement something like that to mark a specific flag as deprecated, and it will appear when the user shows the help message

Do we need a deprecation period for this change? This will break anyone using the old names in scripts and whatnot.
Also, the changes will need something in the release notes so users know about the new names.

Is there a specific way to mark flags as deprecated? I didn't find anything like that in Support/CommandLine. It will be useful if we implement something like that to mark a specific flag as deprecated, and it will appear when the user shows the help message

It would be useful but I don't think we have any such functionality currently. You could either try to pipe in that functionality to the command line APIs, or you could manually implement one-off logic just for include-cleaner, I think either is reasonable.

If Insert or Remove is true, we should diagnose those as being deprecated and recommend using disable-insert or disable-remove instead.

Insert and Remove are true by default. Should it not be as false? Also, the recommendation should be as regular stdout message, or is there a specific function for that?

A release note should be added to clang-tools-extra/docs/ReleaseNotes.rst so users know about the change and new flags.

Is there a specific format for this note?

If Insert or Remove is true, we should diagnose those as being deprecated and recommend using disable-insert or disable-remove instead.

Insert and Remove are true by default. Should it not be as false?

Oops, I meant "if they're used", so yes. :-)

Also, the recommendation should be as regular stdout message, or is there a specific function for that?

llvm::errs() seems to be what the tool currently uses for diagnostics. There's no special helper function in the tool, so you can look at existing uses of llvm::errs() in IncludeCleaner.cpp for uses.

A release note should be added to clang-tools-extra/docs/ReleaseNotes.rst so users know about the change and new flags.

Is there a specific format for this note?

Something along the lines of:

Improvements to include-cleaner
-------------------------------
- Deprecated the ``-insert`` and ``-remove`` command line options, and added
  the ``-disable-remove`` and ``-disable-insert`` command line options as
  replacements. The previous command line options were confusing because they
  did not imply the default state of the option (which is inserts and removes
  being enabled). The new options are easier to understand the semantics of.

✅ With the latest revision this PR passed the C/C++ code formatter.

I think all is fine now

@AaronBallman Do you think we need to work on something in CommandLine to make the deprecation of commands easier and standardised for all tools?

@AaronBallman Do you think we need to work on something in CommandLine to make the deprecation of commands easier and standardised for all tools?

It might be nice, but isn't a requirement for this patch. We don't deprecate command line options too often, so it may not be worth the effort.

LGTM! Do you need me to land the changes on your behalf?

Yup, I don't have access yet

LGTM! Do you need me to land the changes on your behalf?

Yup, I don't have access yet

I'll push the changes once precommit CI goes green. Thank you for the improvement!

LGTM! Do you need me to land the changes on your behalf?

Yup, I don't have access yet

I'll push the changes once precommit CI goes green. Thank you for the improvement!

FYI: it looks like precommit CI found a failure with one of the tests