From 8740bb5e7003c0907138e324870b6284bd568ab2 Mon Sep 17 00:00:00 2001 From: Max Schmeller <6088931+mojomex@users.noreply.github.com> Date: Tue, 12 Nov 2024 08:34:19 +0900 Subject: [PATCH] docs: add contribution guidelines (#202) * docs: initial version of contribution guidelines Signed-off-by: Max SCHMELLER * chore(clang-tidy): add .clang-tidy file mirrored from Autoware Signed-off-by: Max SCHMELLER * docs(contribute.md): add instructions for clang-tidy Signed-off-by: Max SCHMELLER * docs: apply @drwnz's suggestions a.k.a @mojomex's English spelling lessons continue Co-authored-by: David Wong <33114676+drwnz@users.noreply.github.com> * ci(pre-commit): autofix --------- Signed-off-by: Max SCHMELLER Co-authored-by: David Wong <33114676+drwnz@users.noreply.github.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- .clang-tidy | 459 +++++++++++++++++++++++++++++++++++++++++++++ docs/contribute.md | 86 ++++++++- 2 files changed, 544 insertions(+), 1 deletion(-) create mode 100644 .clang-tidy diff --git a/.clang-tidy b/.clang-tidy new file mode 100644 index 000000000..c19664331 --- /dev/null +++ b/.clang-tidy @@ -0,0 +1,459 @@ +Checks: " + -*, + # boost-use-to-string, + # bugprone-argument-comment, + # bugprone-assert-side-effect, + # bugprone-bad-signal-to-kill-thread, + # bugprone-bool-pointer-implicit-conversion, + # bugprone-branch-clone, + # bugprone-copy-constructor-init, + # bugprone-dangling-handle, + # bugprone-dynamic-static-initializers, + # bugprone-exception-escape, + # bugprone-fold-init-type, + bugprone-forward-declaration-namespace, + # bugprone-forwarding-reference-overload, + # bugprone-inaccurate-erase, + # bugprone-incorrect-roundings, + # bugprone-integer-division, + # bugprone-lambda-function-name, + # bugprone-macro-parentheses, + # bugprone-macro-repeated-side-effects, + # bugprone-misplaced-operator-in-strlen-in-alloc, + # bugprone-misplaced-widening-cast, + # bugprone-move-forwarding-reference, + # bugprone-multiple-statement-macro, + # bugprone-not-null-terminated-result, + # bugprone-parent-virtual-call, + # bugprone-posix-return, + # bugprone-signed-char-misuse, + # bugprone-sizeof-container, + # bugprone-sizeof-expression, + # bugprone-string-constructor, + # bugprone-string-integer-assignment, + # bugprone-string-literal-with-embedded-nul, + # bugprone-suspicious-enum-usage, + # bugprone-suspicious-memset-usage, + # bugprone-suspicious-missing-comma, + # bugprone-suspicious-semicolon, + # bugprone-suspicious-string-compare, + # bugprone-swapped-arguments, + # bugprone-terminating-continue, + # bugprone-throw-keyword-missing, + # bugprone-too-small-loop-variable, + # bugprone-unchecked-optional-access, + # bugprone-undefined-memory-manipulation, + # bugprone-undelegated-constructor, + # bugprone-unhandled-self-assignment, + # bugprone-unused-raii, + # bugprone-unused-return-value, + # bugprone-use-after-move, + # bugprone-virtual-near-miss, + # cppcoreguidelines-avoid-goto, + # cppcoreguidelines-init-variables, + # cppcoreguidelines-interfaces-global-init, + # cppcoreguidelines-macro-usage, + # cppcoreguidelines-narrowing-conversions, + # cppcoreguidelines-no-malloc, + # cppcoreguidelines-pro-bounds-pointer-arithmetic, + # cppcoreguidelines-pro-type-const-cast, + # cppcoreguidelines-pro-type-cstyle-cast, + # cppcoreguidelines-pro-type-member-init, + # cppcoreguidelines-pro-type-reinterpret-cast, + # cppcoreguidelines-pro-type-static-cast-downcast, + # cppcoreguidelines-pro-type-union-access, + # cppcoreguidelines-slicing, + # cppcoreguidelines-special-member-functions, + # google-build-explicit-make-pair, + google-build-namespaces, + google-build-using-namespace, + # google-explicit-constructor, + # google-global-names-in-headers, + # google-upgrade-googletest-case, + # hicpp-exception-baseclass, + # hicpp-multiway-paths-covered, + # hicpp-no-assembler, + # hicpp-signed-bitwise, + llvm-namespace-comment, + # misc-definitions-in-headers, + # misc-misplaced-const, + # misc-new-delete-overloads, + # misc-non-copyable-objects, + # misc-redundant-expression, + # misc-static-assert, + # misc-throw-by-value-catch-by-reference, + # misc-unconventional-assign-operator, + # misc-uniqueptr-reset-release, + # misc-unused-alias-decls, + # misc-unused-parameters, + # misc-unused-using-decls, + modernize-concat-nested-namespaces, + # modernize-deprecated-headers, + # modernize-deprecated-ios-base-aliases, + # modernize-loop-convert, + # modernize-make-shared, + # modernize-make-unique, + # modernize-pass-by-value, + # modernize-raw-string-literal, + # modernize-redundant-void-arg, + # modernize-replace-auto-ptr, + # modernize-replace-disallow-copy-and-assign-macro, + # modernize-replace-random-shuffle, + # modernize-return-braced-init-list, + # modernize-shrink-to-fit, + # modernize-unary-static-assert, + # modernize-use-auto, + # modernize-use-bool-literals, + # modernize-use-default-member-init, + # modernize-use-emplace, + # modernize-use-equals-default, + # modernize-use-equals-delete, + # modernize-use-nodiscard, + # modernize-use-noexcept, + # modernize-use-nullptr, + # modernize-use-override, + # modernize-use-transparent-functors, + # modernize-use-uncaught-exceptions, + # modernize-use-using, + # openmp-use-default-none, + # performance-faster-string-find, + # performance-for-range-copy, + # performance-implicit-conversion-in-loop, + # performance-inefficient-algorithm, + # performance-inefficient-string-concatenation, + # performance-inefficient-vector-operation, + # performance-move-const-arg, + # performance-move-constructor-init, + # performance-no-automatic-move, + # performance-no-int-to-ptr, + # performance-noexcept-move-constructor, + # performance-trivially-destructible, + # performance-type-promotion-in-math-fn, + # performance-unnecessary-copy-initialization, + # performance-unnecessary-value-param, + # portability-simd-intrinsics, + # readability-const-return-type, + # readability-container-size-empty, + # readability-convert-member-functions-to-static, + # readability-delete-null-pointer, + # readability-else-after-return, + # readability-function-cognitive-complexity, + # readability-identifier-naming, + # readability-inconsistent-declaration-parameter-name, + # readability-isolate-declaration, + # readability-make-member-function-const, + # readability-misleading-indentation, + # readability-misplaced-array-index, + # readability-non-const-parameter, + # readability-redundant-access-specifiers, + # readability-redundant-control-flow, + # readability-redundant-declaration, + # readability-redundant-function-ptr-dereference, + # readability-redundant-member-init, + # readability-redundant-smartptr-get, + # readability-redundant-string-cstr, + # readability-redundant-string-init, + # readability-simplify-boolean-expr, + # readability-simplify-subscript-expr, + # readability-static-accessed-through-instance, + readability-static-definition-in-anonymous-namespace, + # readability-string-compare, + # readability-uniqueptr-delete-release" + +# WarningsAsErrors: " +# boost-use-to-string, +# bugprone-dangling-handle, +# bugprone-fold-init-type, +# bugprone-inaccurate-erase, +# bugprone-incorrect-roundings, +# bugprone-misplaced-widening-cast, +# bugprone-sizeof-container, +# bugprone-sizeof-expression, +# bugprone-string-constructor, +# bugprone-suspicious-enum-usage, +# bugprone-suspicious-memset-usage, +# bugprone-suspicious-missing-comma, +# bugprone-suspicious-semicolon, +# bugprone-swapped-arguments, +# bugprone-unused-raii, +# bugprone-use-after-move, +# llvm-namespace-comment, +# misc-non-copyable-objects, +# misc-redundant-expression, +# misc-throw-by-value-catch-by-reference, +# misc-unused-alias-decls, +# misc-unused-parameters, +# misc-unused-using-decls, +# modernize-deprecated-headers, +# modernize-redundant-void-arg, +# modernize-use-bool-literals, +# modernize-use-emplace, +# modernize-use-equals-default, +# modernize-use-equals-delete, +# modernize-use-nullptr, +# modernize-use-override, +# modernize-use-using, +# performance-faster-string-find, +# performance-inefficient-algorithm, +# readability-make-member-function-const, +# readability-misleading-indentation, +# readability-misplaced-array-index, +# readability-string-compare" + +HeaderFilterRegex: ^(?!\/usr)(?!\/opt) + +FormatStyle: none + +CheckOptions: + - key: bugprone-argument-comment.CommentBoolLiterals + value: "0" + - key: bugprone-argument-comment.CommentCharacterLiterals + value: "0" + - key: bugprone-argument-comment.CommentFloatLiterals + value: "0" + - key: bugprone-argument-comment.CommentIntegerLiterals + value: "0" + - key: bugprone-argument-comment.CommentNullPtrs + value: "0" + - key: bugprone-argument-comment.CommentStringLiterals + value: "0" + - key: bugprone-argument-comment.CommentUserDefinedLiterals + value: "0" + - key: bugprone-argument-comment.IgnoreSingleArgument + value: "0" + - key: bugprone-argument-comment.StrictMode + value: "0" + - key: bugprone-assert-side-effect.AssertMacros + value: assert + - key: bugprone-assert-side-effect.CheckFunctionCalls + value: "0" + - key: bugprone-dangling-handle.HandleClasses + value: std::basic_string_view;std::experimental::basic_string_view + - key: bugprone-dynamic-static-initializers.HeaderFileExtensions + value: ",h,hh,hpp,hxx" + - key: bugprone-exception-escape.FunctionsThatShouldNotThrow + value: "" + - key: bugprone-exception-escape.IgnoredExceptions + value: "" + - key: bugprone-misplaced-widening-cast.CheckImplicitCasts + value: "0" + - key: bugprone-not-null-terminated-result.WantToUseSafeFunctions + value: "1" + - key: bugprone-signed-char-misuse.CharTypdefsToIgnore + value: "" + - key: bugprone-sizeof-expression.WarnOnSizeOfCompareToConstant + value: "1" + - key: bugprone-sizeof-expression.WarnOnSizeOfConstant + value: "1" + - key: bugprone-sizeof-expression.WarnOnSizeOfIntegerExpression + value: "0" + - key: bugprone-sizeof-expression.WarnOnSizeOfThis + value: "1" + - key: bugprone-string-constructor.LargeLengthThreshold + value: "8388608" + - key: bugprone-string-constructor.WarnOnLargeLength + value: "1" + - key: bugprone-suspicious-enum-usage.StrictMode + value: "0" + - key: bugprone-suspicious-missing-comma.MaxConcatenatedTokens + value: "5" + - key: bugprone-suspicious-missing-comma.RatioThreshold + value: "0.200000" + - key: bugprone-suspicious-missing-comma.SizeThreshold + value: "5" + - key: bugprone-suspicious-string-compare.StringCompareLikeFunctions + value: "" + - key: bugprone-suspicious-string-compare.WarnOnImplicitComparison + value: "1" + - key: bugprone-suspicious-string-compare.WarnOnLogicalNotComparison + value: "0" + - key: bugprone-too-small-loop-variable.MagnitudeBitsUpperLimit + value: "16" + - key: bugprone-unhandled-self-assignment.WarnOnlyIfThisHasSuspiciousField + value: "1" + - key: bugprone-unused-return-value.CheckedFunctions + value: ::std::async;::std::launder;::std::remove;::std::remove_if;::std::unique;::std::unique_ptr::release;::std::basic_string::empty;::std::vector::empty + - key: cert-dcl16-c.NewSuffixes + value: L;LL;LU;LLU + - key: cert-oop54-cpp.WarnOnlyIfThisHasSuspiciousField + value: "0" + - key: cppcoreguidelines-explicit-virtual-functions.IgnoreDestructors + value: "1" + - key: cppcoreguidelines-macro-usage.AllowedRegexp + value: ^DEBUG_* + - key: cppcoreguidelines-macro-usage.CheckCapsOnly + value: "0" + - key: cppcoreguidelines-macro-usage.IgnoreCommandLineMacros + value: "1" + - key: cppcoreguidelines-no-malloc.Allocations + value: ::malloc;::calloc + - key: cppcoreguidelines-no-malloc.Deallocations + value: ::free + - key: cppcoreguidelines-no-malloc.Reallocations + value: ::realloc + - key: cppcoreguidelines-non-private-member-variables-in-classes.IgnoreClassesWithAllMemberVariablesBeingPublic + value: "1" + - key: cppcoreguidelines-pro-type-member-init.IgnoreArrays + value: "0" + - key: cppcoreguidelines-pro-type-member-init.UseAssignment + value: "0" + - key: cppcoreguidelines-special-member-functions.AllowMissingMoveFunctions + value: "0" + - key: cppcoreguidelines-special-member-functions.AllowSoleDefaultDtor + value: "0" + - key: google-readability-braces-around-statements.ShortStatementLines + value: "1" + - key: google-readability-function-size.StatementThreshold + value: "800" + - key: google-readability-namespace-comments.ShortNamespaceLines + value: "10" + - key: google-readability-namespace-comments.SpacesBeforeComments + value: "2" + - key: hicpp-multiway-paths-covered.WarnOnMissingElse + value: "0" + - key: hicpp-signed-bitwise.IgnorePositiveIntegerLiterals + value: "0" + - key: misc-definitions-in-headers.HeaderFileExtensions + value: ",h,hh,hpp,hxx" + - key: misc-definitions-in-headers.UseHeaderFileExtension + value: "1" + - key: misc-throw-by-value-catch-by-reference.CheckThrowTemporaries + value: "1" + - key: misc-unused-parameters.StrictMode + value: "0" + - key: modernize-loop-convert.MaxCopySize + value: "16" + - key: modernize-loop-convert.MinConfidence + value: reasonable + - key: modernize-loop-convert.NamingStyle + value: CamelCase + - key: modernize-make-shared.IgnoreMacros + value: "1" + - key: modernize-make-shared.IncludeStyle + value: google + - key: modernize-make-shared.MakeSmartPtrFunction + value: std::make_shared + - key: modernize-make-shared.MakeSmartPtrFunctionHeader + value: memory + - key: modernize-make-unique.IgnoreMacros + value: "1" + - key: modernize-make-unique.IncludeStyle + value: google + - key: modernize-make-unique.MakeSmartPtrFunction + value: std::make_unique + - key: modernize-make-unique.MakeSmartPtrFunctionHeader + value: memory + - key: modernize-pass-by-value.IncludeStyle + value: google + - key: modernize-pass-by-value.ValuesOnly + value: "0" + - key: modernize-raw-string-literal.ReplaceShorterLiterals + value: "0" + - key: modernize-replace-auto-ptr.IncludeStyle + value: google + - key: modernize-replace-random-shuffle.IncludeStyle + value: google + - key: modernize-use-auto.MinTypeNameLength + value: "5" + - key: modernize-use-auto.RemoveStars + value: "0" + - key: modernize-use-default-member-init.IgnoreMacros + value: "1" + - key: modernize-use-default-member-init.UseAssignment + value: "0" + - key: modernize-use-emplace.ContainersWithPushBack + value: ::std::vector;::std::list;::std::deque + - key: modernize-use-emplace.SmartPointers + value: ::std::shared_ptr;::std::unique_ptr;::std::auto_ptr;::std::weak_ptr + - key: modernize-use-emplace.TupleMakeFunctions + value: ::std::make_pair;::std::make_tuple + - key: modernize-use-emplace.TupleTypes + value: ::std::pair;::std::tuple + - key: modernize-use-equals-default.IgnoreMacros + value: "1" + - key: modernize-use-equals-delete.IgnoreMacros + value: "1" + - key: modernize-use-nodiscard.ReplacementString + value: "[[nodiscard]]" + - key: modernize-use-noexcept.ReplacementString + value: "" + - key: modernize-use-noexcept.UseNoexceptFalse + value: "1" + - key: modernize-use-nullptr.NullMacros + value: "NULL" + - key: modernize-use-override.AllowOverrideAndFinal + value: "0" + - key: modernize-use-override.FinalSpelling + value: final + - key: modernize-use-override.IgnoreDestructors + value: "0" + - key: modernize-use-override.OverrideSpelling + value: override + - key: modernize-use-transparent-functors.SafeMode + value: "0" + - key: modernize-use-using.IgnoreMacros + value: "1" + - key: performance-faster-string-find.StringLikeClasses + value: std::basic_string + - key: performance-for-range-copy.AllowedTypes + value: "" + - key: performance-for-range-copy.WarnOnAllAutoCopies + value: "0" + - key: performance-inefficient-string-concatenation.StrictMode + value: "0" + - key: performance-inefficient-vector-operation.EnableProto + value: "0" + - key: performance-inefficient-vector-operation.VectorLikeClasses + value: ::std::vector + - key: performance-move-const-arg.CheckTriviallyCopyableMove + value: "1" + - key: performance-move-constructor-init.IncludeStyle + value: google + - key: performance-no-automatic-move.AllowedTypes + value: "" + - key: performance-type-promotion-in-math-fn.IncludeStyle + value: google + - key: performance-unnecessary-copy-initialization.AllowedTypes + value: "" + - key: performance-unnecessary-value-param.AllowedTypes + value: .*Ptr;.*SharedFuture + - key: performance-unnecessary-value-param.IncludeStyle + value: google + - key: portability-simd-intrinsics.Std + value: "" + - key: portability-simd-intrinsics.Suggest + value: "0" + - key: readability-function-cognitive-complexity.IgnoreMacros + value: "1" + - key: readability-else-after-return.WarnOnUnfixable + value: "1" + - key: readability-identifier-naming.NamespaceCase + value: lower_case + - key: readability-identifier-naming.ClassCase + value: CamelCase + - key: readability-identifier-naming.PrivateMemberSuffix + value: _ + - key: readability-identifier-naming.StructCase + value: CamelCase + - key: readability-identifier-naming.FunctionCase + value: lower_case + - key: readability-identifier-naming.VariableCase + value: lower_case + - key: readability-identifier-naming.GlobalConstantCase + value: lower_case + - key: readability-identifier-naming.GlobalConstantPrefix + value: g_ + - key: readability-identifier-naming.ConstexprVariableCase + value: lower_case + - key: readability-inconsistent-declaration-parameter-name.IgnoreMacros + value: "1" + - key: readability-inconsistent-declaration-parameter-name.Strict + value: "0" + - key: readability-redundant-smartptr-get.IgnoreMacros + value: "1" + - key: readability-redundant-string-init.StringNames + value: ::std::basic_string + - key: readability-simplify-subscript-expr.Types + value: ::std::basic_string;::std::basic_string_view;::std::vector;::std::array + - key: readability-static-accessed-through-instance.NameSpecifierNestingThreshold + value: "3" diff --git a/docs/contribute.md b/docs/contribute.md index f0a80b161..e86e06ccc 100644 --- a/docs/contribute.md +++ b/docs/contribute.md @@ -1,3 +1,87 @@ # Contributing to Nebula -WIP - please check back soon! +Thank you for your interest in contributing to Nebula! +We’re excited to work with the open-source community to build an even better project. +Before submitting your contributions, please take a moment to review our guidelines to ensure a smooth process. + +## Getting Started + +- Set up your development environment: [installation](installation.md) +- Enable pre-commit + + ```shell + # Install pre-commit on your system + pip3 install pre-commit + + # Enable pre-commit for Nebula + cd ~/nebula_ws/src + pre-commit install + ``` + +- Set up your IDE to use Clang-Tidy with the `.clang-tidy` configuration found in the repository root +- Documentation can be found at [tier4.github.io/nebula](https://tier4.github.io/nebula) + +## How to Contribute + +### About large contributions + +For large contributions, i.e. more than a few dozen lines or new features, +[create an issue](https://github.com/tier4/nebula/issues/new) first. +This allows us to give feedback early and allows for discussion about how/if the feature fits into +Nebula. + +Once an issue is ready to be turned into a PR, make sure to comment on the issue that you are currently working on it. +This prevents double work from other community members. + +Do not be afraid to open a draft PR in an early stage of your implementation. +This gives us a chance to spot potential problems early (e.g. line count) and lets us align with you better. + +### What gets merged? + +We are keen on merging PRs that are clear wins for the project: + +- Support for popular sensor models +- Unit tests +- Bug fixes +- Improvements for robustness, error handling, and reporting + +If a PR has value for the project but takes a long time or a lot of effort to review, +we will have to reject it. We will let you know if we think we can handle the scope of your +contribution in the discussion of your issue. + +### What doesn't get merged? + +- 500+ line PRs: split your PR into smaller ones +- PRs without sufficient unit tests: if unit tests are not rigorous enough or have low coverage +- PRs with multiple unrelated changes: split up into multiple PRs +- Performance-heavy features: features with latency increases of more than a low single-digit percentage +- Style changes +- Big refactorings +- Features implemented only for some vendors + +## Pull Requests + +Pull requests should be against the `develop` branch. +Hotfix PRs should be against the `main` branch. + +A good PR fulfills all of the following: + +- Passes pre-commit +- Conforms to the repo's `.clang-tidy` and `.clang-format` +- Passes all CI checks +- Has a single clearly stated goal +- Every line changed directly contributes to that goal +- Includes unit tests for added/fixed functionality where applicable +- New functionality is documented +- Has a reproducible evaluation/testing method where applicable + - e.g. Rosbags or PCAPs attached + - Easily runnable benchmarks are included for performance optimizations + +We cannot start a review before pre-commit and CI are passing. + +## Other Ways to Contribute + +Bug reports in GitHub issues: + +- Please provide logs, PCAPs and videos where possible +- Make sure you always specify the exact version and environment used