[sane-devel] [janitorial] Text file style convention "enforcement"

[Olaf Meeuwissen]

Hi all,

It's been a while since my last janitorial.  Interest in contributing to
the project comes in waves.  I've been preoccupied with the preparations
for the 1.0.27 release.  During which, Aaron made a suggestion about how
coding style conventions could help spot bugs[1].  I followed up with an
"apologetic" reply[2] why I didn't want to enforce a *coding* style, but
at the same time mentioned some, hopefully, non-controversial rules for
all text files.

 [1] https://lists.alioth.debian.org/pipermail/sane-devel/2017-May/035353.html
 [2] https://lists.alioth.debian.org/pipermail/sane-devel/2017-May/035355.html

Well, I applied those rules and pushed the result.  Here are the rules:

 - all text files shall be UTF-8 encoded
 - all lines shall end in non-whitespace
 - all files shall end with a newline
 - all files shall end with a non-empty line

# I wondered what to do with leading empty lines but decided not to
# touch these (for now).  They might serve some sort of "aesthetic"
# purpose.  I also noticed a note on "follow the GNU coding standards"
# in doc/backend-writing.txt (and shied away from that, for now?).  As
# for the tab vs spaces mess?  Let's leave that for later.

Cool.  Now what?  How does this affect you?  How do I "oblige" to this?
How do you "enforce" this?

First, the effect on people working with the SANE backend repository.
Any of your changes may now cause conflict when you try to merge with,
rebase on or apply patches to the `master` branch.  Most of the pain can
be alleviated with the various `--ignore-*` flags to the command you use
to do that.  The `git help` comman for your action of choice has details
on how this works, as does the `patch` manual page.

# If you use a GUI to do this, check its documentation.  There should be
# an option to set those flags, on a one-time basis or as a preference.
# If not, submit a feature request for that GUI.

The "rules" are laid down in a `.editorconfig` file in the repository.
If your editor or IDE is supported by EditorConfig, you're all set.  If
your editor or IDE needs a plugin, do yourself a favour and install it.
The EditorConfig[3] documentation has info on supported plugins[4].
It's not difficult and works wonders.  Been there, done that myself and
am now happily using the Emacs plugin and Emacs now makes sure I follow
the "rules".

 [3] http://editorconfig.org/
 [4] http://editorconfig.org/#download

If your editor or IDE is not supported by EditorConfig, do not despair.
First submit an issue[5] asking for a "new plugin" (use the label!) ;-)

 [5] https://github.com/editorconfig/editorconfig/issues/new

While waiting for that plugin (or hacking up one yourself), you can use
the `tools/style-check.sh` script to check files.  It also has a `--fix`
option that will take care of the newline and whitespace issues.  Seeing
the encoding cannot be guessing automagically, any compliance violations
for the UTF-8 rule need to be handled manually.

Want to make this even simpler?  No sweat.  Just add the attachment to
your `.git/hooks/pre-commit` file (or add it if you don't have one).
Note that the file needs execute permissions.  A simple

  chmod 0755 .git/hooks/pre-commit

will do that trick.

# For those of you that don't have an `xargs` that supports the `-r`
# option, which is a GNU extension, you can rewrite the pipe to use a
# `while read file` loop.  Don't know how?  Just ask!
# Parallelization afficionados can play with the `-P` and `-n` options
# to `xargs` if so inclined.

The pipeline over at GitLab.com[6] will shortly (tomorrow?) be modified
to run the `tools/style-check.sh` before running any builds.  Failing
that check will torpedo the build, just like compiler warnings on Debian
stable.

 [6] https://gitlab.com/sane-project/backends/pipelines

Hope this helps (and doesn't ruffle too many feathers ;-)
--
Olaf Meeuwissen, LPIC-2            FSF Associate Member since 2004-01-27
 GnuPG key: F84A2DD9/B3C0 2F47 EA19 64F4 9F13  F43E B8A4 A88A F84A 2DD9
 Support Free Software                        https://my.fsf.org/donate
 Join the Free Software Foundation              https://my.fsf.org/join
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: pre-commit
URL: <http://lists.alioth.debian.org/pipermail/sane-devel/attachments/20170531/b1daa19a/attachment.ksh>