CONTRIBUTING: Move "Coding language and style" section

Message ID 20211211175822.950836-1-thomas@codesourcery.com
State Committed
Headers
Series CONTRIBUTING: Move "Coding language and style" section |

Commit Message

Thomas Schwinge Dec. 11, 2021, 5:58 p.m. UTC
  This section got added in commit 4f8c9b170d80b920d13e8f291b347df74db34307
"Use C++11 for the code base", but unfortunately got placed in the middle
of the "Regression tests" section.  Move it after that one.

	* CONTRIBUTING: Move "Coding language and style" section.

Signed-off-by: Thomas Schwinge <thomas@codesourcery.com>
---
 CONTRIBUTING | 110 +++++++++++++++++++++++++--------------------------
 1 file changed, 55 insertions(+), 55 deletions(-)
  

Comments

Dodji Seketeli Dec. 17, 2021, 6:59 p.m. UTC | #1
Hello,

Thomas Schwinge <thomas@codesourcery.com> a écrit:

[...]

>  CONTRIBUTING | 110 +++++++++++++++++++++++++--------------------------
>  1 file changed, 55 insertions(+), 55 deletions(-)
>
> diff --git CONTRIBUTING CONTRIBUTING

I am not sure why, but on patches I use and receive, this line looks
like:

diff --git a/CONTRIBUTING b/CONTRIBUTING

See the difference of format?  This is what I get using git
format-patch.

I am not sure why yours is different.  Any idea?  I am using git 2.33.

In any case, when I do "git am" on your patch, git refuses to apply it.
I had to edit the patch so that the line looks like:

diff a/CONTRIBUTING b/CONTRIBUTING

at least.

[...]

> This section got added in commit 4f8c9b170d80b920d13e8f291b347df74db34307
> "Use C++11 for the code base", but unfortunately got placed in the middle
> of the "Regression tests" section.  Move it after that one.
>
> 	* CONTRIBUTING: Move "Coding language and style" section.
>
> Signed-off-by: Thomas Schwinge <thomas@codesourcery.com>

Applied to master.  Thanks!

[...]

Cheers,
  
Thomas Schwinge Dec. 17, 2021, 10:06 p.m. UTC | #2
Hi Dodji!

On 2021-12-17T19:59:35+0100, Dodji Seketeli <dodji@redhat.com> wrote:
> Thomas Schwinge <thomas@codesourcery.com> a écrit:
>>  CONTRIBUTING | 110 +++++++++++++++++++++++++--------------------------
>>  1 file changed, 55 insertions(+), 55 deletions(-)
>>
>> diff --git CONTRIBUTING CONTRIBUTING
>
> I am not sure why, but on patches I use and receive, this line looks
> like:
>
> diff --git a/CONTRIBUTING b/CONTRIBUTING
>
> See the difference of format?  This is what I get using git
> format-patch.
>
> I am not sure why yours is different.  Any idea?

Yes: local 'git diff' configuration unintentionally leaked into
'git format-patch' as used by 'git send-email'.  I've fixed this;
later patches should apply fine as sent.

> In any case, when I do "git am" on your patch, git refuses to apply it.
> I had to edit the patch so that the line looks like:
>
> diff a/CONTRIBUTING b/CONTRIBUTING
>
> at least.

..., or -- as you supposedly have found out a few minutes later ;-) --
apply with "git am -p0".  Sorry for that.


Grüße
 Thomas
-----------------
Siemens Electronic Design Automation GmbH; Anschrift: Arnulfstraße 201, 80634 München; Gesellschaft mit beschränkter Haftung; Geschäftsführer: Thomas Heurung, Frank Thürauf; Sitz der Gesellschaft: München; Registergericht München, HRB 106955
  

Patch

diff --git CONTRIBUTING CONTRIBUTING
index 3a2073b3..24a483b2 100644
--- CONTRIBUTING
+++ CONTRIBUTING
@@ -99,61 +99,6 @@  So, to be complete the regression checking command to run against your
 patch should be: "make check-self-compare distcheck-fast -j16", if you have
 a machine with a 16 threads processors, for instance.
 
-Coding language and style
-==========================
-
-The coding style is self evident when reading the source code.  So
-please, stick to and mimic what is already in there for the sake of
-consistency at very least.  Just for history, it's derived from the
-style of the C++ standard library from the GNU project.
-
-As of libabigail 2.0, the language we use is C++ 11.  The level
-supported is the one supported by the GCC 4.8.x series of compilers.
-This should be old and well tested enough to be supported by your
-current favorite compiler.
-
-Initially, the code base of the project was written in C++03, with the
-TR1 extensions.  That heritage is well visible in the code base as it
-is today.
-
-Please do not rush and send gazillions of patches that just re-write
-tons of code into your favorite C++ 11 flavour du jour.  We will
-likely reject those patches.  We want to keep the history of the code
-base in such a way that tools like "git blame <sourcefile> are still
-useful.
-
-So we'll accept patches changing parts of the code base to more recent
-C++ 11 constructs only if you happen to add functionality or fix
-things in that area.  If it makes "cultural common" sense to adopt
-those constructs.  What I mean by "cultural" is that must make sense
-in relative to the culture of the project.  And yes, that is
-subjective.  Sorry.
-
-As a generic rule, we tend to favor the lowest possible level of
-abstraction that makes sense without requiring future maintainers of
-the project to have a PhD in design patterns.  We are not impressed by
-design patterns.  We use them where they make clear sense, but we
-don't idolize them.  Put it another way, we will always favor the one
-who *READS* and debug the code over the one who writes it.  To put
-things in a hypothetical perspective, we'll rather accept a repetitive
-code that stays simple to read and debug over a highly abstract one
-using meta programming to save a few lines of repetitive code located
-in a very small number of places.
-
-Really, in this project, we care about low level binary analysis
-stuff.  Issues in that area can be hard to reproduce and quite
-challenging to debug.  So having tons of abstraction layers in the
-code base have proven to be a maintenance burden over the years, from
-our experience in working on similar projects.  So please help us
-avoid those mistakes that we make just for the pleasure of writing
-what can look as "pleasant code" at a first naive sight.
-
-That being said, we also love cleanly designed APIs that are fairly
-re-usable and well documented.  And we also praise abstraction and
-modularisation that we recognize as being the most basic tools of any
-engineer.  So we like to think about ourselves as well rounded people
-who care about maintaining things for a long time to come :-)
-
 Launching regression tests in Valgrind
 --------------------------------------
 
@@ -229,6 +174,61 @@  make sure to add your new test input files to the
 tests/data/Makefile.am file, in the EXTRA_DIST variable.  Look at how
 things are organized in that file, and please do things similarly.
 
+Coding language and style
+==========================
+
+The coding style is self evident when reading the source code.  So
+please, stick to and mimic what is already in there for the sake of
+consistency at very least.  Just for history, it's derived from the
+style of the C++ standard library from the GNU project.
+
+As of libabigail 2.0, the language we use is C++ 11.  The level
+supported is the one supported by the GCC 4.8.x series of compilers.
+This should be old and well tested enough to be supported by your
+current favorite compiler.
+
+Initially, the code base of the project was written in C++03, with the
+TR1 extensions.  That heritage is well visible in the code base as it
+is today.
+
+Please do not rush and send gazillions of patches that just re-write
+tons of code into your favorite C++ 11 flavour du jour.  We will
+likely reject those patches.  We want to keep the history of the code
+base in such a way that tools like "git blame <sourcefile> are still
+useful.
+
+So we'll accept patches changing parts of the code base to more recent
+C++ 11 constructs only if you happen to add functionality or fix
+things in that area.  If it makes "cultural common" sense to adopt
+those constructs.  What I mean by "cultural" is that must make sense
+in relative to the culture of the project.  And yes, that is
+subjective.  Sorry.
+
+As a generic rule, we tend to favor the lowest possible level of
+abstraction that makes sense without requiring future maintainers of
+the project to have a PhD in design patterns.  We are not impressed by
+design patterns.  We use them where they make clear sense, but we
+don't idolize them.  Put it another way, we will always favor the one
+who *READS* and debug the code over the one who writes it.  To put
+things in a hypothetical perspective, we'll rather accept a repetitive
+code that stays simple to read and debug over a highly abstract one
+using meta programming to save a few lines of repetitive code located
+in a very small number of places.
+
+Really, in this project, we care about low level binary analysis
+stuff.  Issues in that area can be hard to reproduce and quite
+challenging to debug.  So having tons of abstraction layers in the
+code base have proven to be a maintenance burden over the years, from
+our experience in working on similar projects.  So please help us
+avoid those mistakes that we make just for the pleasure of writing
+what can look as "pleasant code" at a first naive sight.
+
+That being said, we also love cleanly designed APIs that are fairly
+re-usable and well documented.  And we also praise abstraction and
+modularisation that we recognize as being the most basic tools of any
+engineer.  So we like to think about ourselves as well rounded people
+who care about maintaining things for a long time to come :-)
+
 Sign your work
 ==============