From 06c570e15997ff184dab2787823aae9dd05060b4 Mon Sep 17 00:00:00 2001 From: Wilson Snyder Date: Tue, 5 Aug 2025 17:52:34 -0400 Subject: [PATCH] Commentary --- docs/internals.rst | 46 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/internals.rst b/docs/internals.rst index 816d457f7..a572a67f6 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -1143,7 +1143,7 @@ is appreciated if you could match our style: calls. (This convention has not been applied retroactively.) C and Python indentation is automatically maintained with "make format" -using clang-format version 10.0.0, and yapf for python, and is +using clang-format version 14.0.0, and yapf for Python, and is automatically corrected in the CI actions. For those manually formatting C code: @@ -1158,6 +1158,50 @@ code: parenthesis (only applies to functions; if/else has a following space). +Commit messages +--------------- + +Pull requests do not typically edit ``Changes`` in order to reduce +potential merge conflicts. Instead, contibutors should use an appropriate +first line of the git commit message. Maintainers periodically run +``nodist/log_changes`` which analyzes the commit messages to suggest edits +to the ``Changes`` file. + +The format of a commit message should be typically of the forms below. The +github issue number, and github pull number if different should be +included. + +"Add (#1234)" + For adding a new feature. +"Fix (#1234)" + For a bug fix. +"Improve (#1234)" + For improving something that previously existed. +"Optimize (#1234)" + For improving performance. +"Support (#1234)" + For features that are described by IEEE were previously not supported. +"Commentary" + For a super-trivial change to e.g. documentation. + These will typically not get described in the Changes file. +"CI: (#1234)" + For changes that only concern github actions. + These will typically not get described in the Changes file. +"Tests: (#1234)" + For changes that only concern tests. + These will typically not get described in the Changes file. +"Internals: (#1234)" + For changes that only concern developers, e.g. code cleanups. + These will typically not get described in the Changes file. + +The line's grammar should match the phrasing used in the Changes file. + +If the change does not affect user-visible function, also add "No +functional change." if it's 99% certain not to change behavior, or "No +functional change expected." if no change was expected but there may be +uncertanty. + + The ``astgen`` Script ---------------------