[sane-devel] [janitorial] Text file style convention "enforcement"
paddy-hack at member.fsf.org
Wed May 31 12:41:40 UTC 2017
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. I followed up with an
"apologetic" reply 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.
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 documentation has info on supported plugins.
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
If your editor or IDE is not supported by EditorConfig, do not despair.
First submit an issue asking for a "new plugin" (use the label!) ;-)
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 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
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...
More information about the sane-devel