Re: Configuration Convention

On Mon, Mar 5, 2012 at 8:14 PM, Intransition <[e-mail]> wrote:
> This is probably one of this topics that will get little attention.
> Nonetheless...
>
> Have other developers started to feel like the *configuration* files for =
all
> the various project tools they use are starting to overshadow the rest of
> the project files?

My first gut reaction was of agreement, "yes, I do!" since I'd
recently pretty much thought the same thing recently about an
open-source ruby project hosted on GitHub.

However, after thinking about it more while reading through your list
(below), I realize that this was only a passing thought and that I
don't really feel this way, at least not completely (more on this
later).

>=C2=A0For instance, In many of my projects the meat of the
> project consists of a few source directories `lib/`, `test` (or `spec`) a=
nd
> sometimes `bin/`, usually four general documentation files
> `README`,=C2=A0`HISTORY`, `LICENSE` and `MANIFEST` and then of a few non
> vcs-tracked things like `pkg/`, `log/` and `web/` directories. All the re=
st
> consist of various configuration tool files. A quick look at various
> projects on github provides:
>
> * .git
> * .gitignore

Since these have nothing to do with ruby and are simply an artifact of
the VCS in use, at most they may add "dotfile fatigue" when viewing
the list of all files in a clone of the project. Even if an opt-in,
ruby-wide, project structure convention is agreed-upon, it can't/won't
be able to comment on these types of files, per se.

> * .document
> * .rdoc_options
> * .yardopts
> * .yardoc
> * .autotest
> * .travis.yml
> * .rspec
> * .ruby
> * .test
> * .braids
> * .vclog
> * .rvmrc
> * .rbenv-version
> * .test-unit.yml
> * .gemtest
> * .gemspec -or-=C2=A0foo.gemspec

After thinking about this list, I realize I already put up with loads
of "dotfiles" in my "home" directory on any Un*x system already, which
system works great since the default behavior of the `ls` command is
to "hide" dotfiles from me unless I ask to see them.

I recon I'm okay with projects having dotfiles in the project root
since it's a well-established convention already. I'm even okay with
the fact that some projects commit some of these files into the
project's repository (as opposed to individuals simply having their
own personal, local copies).

However, I "feel" that a project should consider adding dotfiles to
the project's code repo as the exception to the more general rule of
having your [D]VCS ignore them by default. I also generally feel that
dotfiles should be reserved for the build, test suite, packaging, and
[D]VCS management tools, which is already pretty much the case for
most files. So I think we've already *got* a good convention going
already, IMHO.

> * Guardfile
> * Rakefile
> * Gemfile
> * Gemfile.lock
> * Procfile

Hmm, I feel a little differently about these "Configfiles". I get the
lineage, these harkening back to the standard Makefile convention, the
capitalization making this file stand apart. Rakefile is the new, ruby
equivalent of the Makefile. Then came the Gemfile and several other
projects have their Awsomefile too.

I'd like any convention, however [un]official to steer developers from
taking up too much namespace with just Anyoldfile. I'm not sure what
gem/project uses Procfile or Guardfile so I can't comment on these
(I'm too lazy too Google them right now). I just know that I'll
generally be very conservative and won't create a gem/lib that has a
Configfile unless it really, really makes sense. I'll also steer away
from using "just any ol' project" that (mis)uses any convention too
much in a manner with which I disagree, without offering enough good,
bug-free functionality to make it worth it.

> * config.ru

Hmm. Not sure what I would've recommended the standard rack
application definition file to be had I been involved, but my first
thought is that I'm not a fan of this and I hope that other projects
don't go too far with this convention of "config.my-extension".

>
> And there are no doubt many more. Feel free to mention notable ones I've
> missed.
>
> Now, obviously not all of these will apply to every project. But I can
> imagine that given enough time and a rather=C2=A0thorough developer, a
> project=C2=A0could acquire configurations for a couple dozen tools. Think=
 code
> coverage, code analysis, IDE/RAD configuration, etc. I suspect there is a
> saturation point --at some point it just becomes too much to remember. Ev=
en
> so, it could amount to quite a few files, well exceeding the number of
> toplevel "meat" files of a project.
>
> Another thing to notice is that there are almost universally two file
> formats:=C2=A0Ruby or YAML,=C2=A0and three naming schemes: dot files, Foo=
file files
> and lowercase with special extension files.

If your config file is ruby (and isn't a Configfile), I'd prefer it
still have the standard "rb" extension. Rake cut out its own extension
of *.rake but I hope no one gets too crazy adding custom extensions.

Likewise, if your config format is YAML, please *use* a "yml" or
"yaml" extension to make it clear. Just my opinion -- it might be your
conventionally named config file, but if it uses another
language/markup internally, please use that language/markup's naming
convention (this would also apply to JSON, XML, etc, though these are
notably uncommon in ruby projects). It's true that a quick glance can
almost always tell me the format, but still....

>
> While there are obviously some files that will always remain (e.g. .git),=
 I
> wonder if it is possible for a convention to ever develop to mitigate all
> this. Most likely that would be in the form of a common directory to hold
> all these files, although conceivably, it could be in the form of a coupl=
e
> of shared files --one for Ruby code and one for YAML.
>
>

Now, for application-level configuration, I like the convention used
by several existing libraries and frameworks of having a "config"
directory to hold all your configuration files. However, the kinds of
files listed above aren't application-level config files, but
"application-development-level" tools. These kinds of files *should*
stay in the root of the application folder, IMHO, just like I expect
my system application's to keep my personal configurations in the root
of my user directory using dotfiles or dot-directories. App-level
configs can continue to go in a "config" directory.

Just FYI, I have my own convention I've used twice now with two rails
apps, where my application level configs (YAML files inside the
"config" directory) make use of both the "yml" and "yaml" extension.
All my "config/*.yml" files are ignored and are *not* added to my code
repository, being local deployment-specific configurations (such as
the rails standard "config/database.yml"). For all other
application-level config files that contain configuration that isn't
deployment- or host-specific (and doesn't ever contain any kind of
credential or token) uses the "config/*.yaml" namespace and *does* get
added to the repo. Finally, for each "config/*.yml" file that my
application needs, I do commit a generic version with the "*.yml-dist"
extension. I've just picked this up from various other blogs/projects
and it generally works. However, that's all a little off topic though.

In summary, I feel that basically/overall, a good, de facto convention
is already being followed with me favoring a default attitude of not
commiting application-development-level configs, using dotfiles while
avoiding Configfiles and config.custom-extension files.

That's my $0.02

--=20
Kendall Gifford
[e-mail]