RFC: Better commit messages for libstdc++

[Thomas Rodgers]

+1 concur

Jonathan Wakely writes:

> With the conversion from Subversion to Git now scheduled for the end
> of this year (see https://gcc.gnu.org/wiki/GitConversion for the
> plans) I think it's time to consider a policy for better commit
> messages.
>
> I want all commits to libstdc++ to include a one-line summary message,
> with a blank line before the rest of the message. This should be a
> hard requirement. We can do this now, we don't need to wait until we
> stop using Subversion. Ideally this would also be adopted for the rest
> of GCC, but I'll start with libstdc++.
>
> I suggest reading https://chris.beams.io/posts/git-commit/ if you
> don't already agree :-)
>
> Currently the output of 'git log --oneline' is often unreadable.
> There are lots of entries which just past the ChangeLog entry, so the
> first line is just the date and committer's name and email address.
> That's not useful as a summary of the commit. Other commits show the
> list of changed files, which is too detailed, a summary would be
> better.
>
> 2d9c100659d Implement LWG 3255 for std::span constructors
> 047fcaf1e11 PR libstdc++/77936 remove unused variable
> c6fd1c4cf03 [PR 91853] Prevent IPA-SRA ICEs on type-mismatched calls
> 9ce1ca72088 2019-09-30  Andreas Tobler  <andreast@gcc.gnu.org>
> 70f0835d2a9 	PR target/91931 	* config/i386/i386-expand.c (ix86_expand_adjust_ufix_to_sfix_si): Use 	gen_int_mode instead of GEN_INT.
> ed76597323f Daily bump.
> ef6064d4ff4 2019-09-29  Steven G. Kargl  <kargl@gcc.gnu.org>
> 0c7c01cf936 [Darwin, PPC, Mode Iterators 5/n] Update macho_low.
> a3310563550 2019-09-29  Steven G. Kargl  <kargl@gcc.gnu.org>
> e020479cd65 2019-09-29  Paul Thomas  <pault@gcc.gnu.org>
> e9eb6ea5605 	PR bootstrap/90543 	* optc-save-gen.awk: Fix up printing string option differences.
> 56f22142aba gcc/ChangeLog
> 49f75e008c0 This patch is to add the support for float from/to long conversion vectorization on port rs6000.
> 8ee0996558f 2019-09-28  Jerry DeLisle  <jvdelisle@gcc.ngu.org>
> 1cbc7e9bf01 Daily bump.
> a4fcce58dff 2019-09-28  François Dumont  <fdumont@gcc.gnu.org>
> 1334eb86c38 [Darwin, PPC, Mode Iterators 4/n] Update macho_high.
> cb9a5db89bd 2019-09-28  Jerry DeLisle  <jvdelisle@gcc.gnu.org>
> 9587be52124 2019-09-28  Steven G. Kargl  <kargl@gcc.ngu.org>
> c6331a1f238 2019-09-28  Steven G. Kargl  <kargl@gcc.gnu.org>
> aeca84f4c1e 	PR c++/91889 - follow-up fix for DR 2352. 	* call.c (involves_qualification_conversion_p): New function. 	(direct_reference_binding): Build a ck_qual if the conversion 	would involve a qualification conversion. 	(convert_like_real): Strip the conversion created by the ck_qual 	in direct_reference_binding.
> e95722140ec 	PR c++/91921 - stray warning with -Woverloaded-virtual. 	* class.c (warn_hidden): Only emit the second part of 	-Woverloaded-virtual if the first part was issued.  Use inform instead 	warning_at.
> 6d88a6b8c4f 	PR c++/91923 - failure-to-SFINAE with class type NTTP in C++17. 	* pt.c (invalid_nontype_parm_type_p): Only emit errors when 	tf_error.
> 492c602a810 gcc/ 2019-09-28  Oleg Endo  <olegendo@gcc.gnu.org>
> 67e0527b1bd gcc/ 2019-09-28  Oleg Endo  <olegendo@gcc.gnu.org>
> dcfd68ec29a Fix endian issue in pr91656 testcases
> f840368602b     compiler: resolve importing ambiguity for more complex function calls
> 1eedf33ccdc Daily bump.
> a8864f4a61a Regenerate `configure' scripts for `uclinuxfdpiceabi' libtool.m4 update
> 853517aff15 	PR c++/88203 c-family/ 	* c-common.h (c_omp_predefined_variable): Declare. 	* c-omp.c (c_omp_predefined_variable): New function. 	(c_omp_predetermined_sharing): Return OMP_CLAUSE_DEFAULT_SHARED 	for predefined variables. c/ 	* c-parser.c (c_parser_predefined_identifier): New function. 	(c_parser_postfix_expression): Use it. 	(c_parser_omp_variable_list): Parse predefined identifiers. 	* c-typeck.c (c_finish_omp_clauses): Allow predefined variables 	in shared and firstprivate clauses, even when they are predetermined 	shared. cp/ 	* parser.c (cp_parser_omp_var_list_no_open): Parse predefined 	variables. 	* semantics.c (finish_omp_clauses): Allow predefined variables in 	shared and firstprivate clauses, even when they are predetermined 	shared. 	* cp-gimplify.c (cxx_omp_predetermined_sharing_1): Return 	OMP_CLAUSE_DEFAULT_SHARED for predefined variables. testsuite/ 	* c-c++-common/gomp/pr88203-1.c: New test. 	* c-c++-common/gomp/pr88203-2.c: New test. 	* c-c++-common/gomp/pr88203-3.c: New test.
>
> This last one is particularly bad!
>
> Take a look at 'git log --oneline --author=redi' for how it should
> look:
>
> 2d9c100659d Implement LWG 3255 for std::span constructors
> 047fcaf1e11 PR libstdc++/77936 remove unused variable
> 29a4c7d93a6 PR libstdc++/91910 fix data race in Debug Mode destructors
> 563af6e4987 Define std::to_array for Debug Mode
> f875c1ba2b0 Implement C++20 constexpr changes to std::pair (P1032R1)
> b860dbe9791 Fix array index error in address_v6 comparisons
> d00ba20dbd7 Remove include directives for deleted Profile Mode headers
> 17404fb2aa2 Implement LWG 3296 for basic_regex::assign
> 3efa913a6e4 Remove check for impossible condition in std::variant::index()
> 4c6edff3676 PR libstdc++/91871 fix Clang warnings in testsuite
> de61fb434a5 PR libstdc++/91788 improve codegen for std::variant<T...>::index()
> c3ae6f9b28e PR libstdc++/91748 fix std::for_each_n for random access iterators
> 0f5caaa9b5f Fix Xmethod for shared_ptr::use_count()
> 25f120f074c Fix libstdc++ tests for -Wvolatile warnings in C++2a mode
> e4c0b7eac16 Implement std::common_reference for C++20
>
>
> The format I'd like to see for libstdc++ commits is shown below. If
> the change is fixing a bug or implementing a WG21 proposal or issue,
> that should be mentioned in the summary. Typically, the summary would
> make a good email Subject: line, and the paragraphs following the
> summary would make a good email body describing the patch (everybody
> is already writing an email Subject and an email body, so there is no
> extra work needed to reuse t hat text in the commit message). The
> ChangeLog entry should be provided at the end, just like it is today.
> The only difference is that a summary line is required before the
> changelog text, and a descriptive body is encouraged.
>
>
> Proposed format:
>
> PR libstdc++/NNNNN one-line summary of the change
>
> Optional additional text describing the change here. You can use this
> to describe the problem being solved, and how the patch addresses it.
> This can be as long or short as you like, in multiple paragraphs if
> you want (or omitted entirely if there's nothing useful that isn't
> already said by the summary line and the changelog).
>
>    YYYY-MM-DD  John Doe  <jdoe@example.com>
>
>    * foobar.cc: standard GNU changelog at the end.