add unit tests, docs related to available log level names

[salewski]

This PR adds some unit tests and freshens up docs related to logging levels.

This work started as an effort to provide unit tests that exercise simple scenarios in which a single logging level is specified for the entire application (without any more specific logging directives). It grew into a bit of a doc updating effort, too.

The unifying theme behind the individual commits in this series is the surfacing of simple facts about the env_logger crate. These changes help provide answers to some fairly basic questions such as:

• "What log levels are available?"
• "Is INFO allowed in addition to info?"
• "How do I configure it?"
• "Does it have a config file?"
• "How do I make it write to a log file?"
• "How do I completely disable logging?"

The doc changes also include fixes to some contradictory statements about what the default behavior is.

Most of this is just gathering data from elsewhere else and putting it where people are already looking (info from the README.md file that wasn't in the crate-level API docs (or vice versa); info that can be guessed at from glancing at the log crate's API docs, but which are important for using env_logger with confidence; and so on). The idea is that the user reading the crate-level API docs on crates.io should get roughly the same sense for the crate as does the person reading the project's 'README.md' file on GitHub.

The newly added unit tests exercise functionality in a way that is more basic than the existing tests (that involve more sophisticated logging directives). These new tests also serve as easy to locate in-tree examples of simple use.

All in all, these changes help make the documentation of env_logger more self contained -- able to stand better on its own, and with less reliance on the user's familiarity with the log crate.

[salewski]

Heads-up: The failed CI check is unrelated to this PR.

The "Check formatting" check is complaining about a trailing comma on an existing line of code, not something introduced here.

[salewski]

@jplatte Thanks for the review!

Thanks for the PR, I like the improved docs!

I've now fixed the rustfmt issue on the master branch, could you rebase?

Sure; I'll do that as soon as I make the adjustments outlined below.

Also, why do your commit messages all start with [N of 9]:? I've seen this before but don't really understand what value it provides.

It's mainly a way of organizing work informed by experience reviewing patch series in email threads. It attaches to a commit useful metadata that will live with the commit indefinitely (unless it gets removed in a future rebase or "squash and merge"). Having that small bit of metadata handy avoids the need to re-derive it, and provides a number of small benefits that can make things easier to manage, especially when working with a large number of projects and branches within those projects.

• Personal commit management during development: While working on a change (always on a dedicated branch), the numbering helps with managing the individual commits across rebases, of which I do tons.

  I don't usually sit down to write a patch series, but rather "just one small patch...". While trying to keep commits small and self-contained, one change grows into to two, two grows into three, and so on, and they almost never flow out in the same order as the final sequence. They continually get split apart, squashed together, and rearranged via rebases throughout.

  Because Emacs and Magit make interactive rebases so easy, I do tons of them. Most never get pushed anywhere; they're just cyclical refinements made on my local branch leading up to the thing that eventually gets pushed.

  Those interactive rebases involve nudging individual commits "up" and "down" in the order, inserting "fixup" and "squash" merges in between them, and similar things. That type of activity is more difficult for me to screw up when the commit messages have numbers on them.

  I can also do the rebases more quickly when I can focus on the locality of the sequence numbers, which I already thought through at some earlier time when assigning the numbers. I do not have to again get my head into the context of each of those individual commits and redo the total sequencing.

  The numbers help to tell at a glance how the change series is sizing up. As it evolves, I frequently inspect the output of:

       $ git log --pretty=oneline --no-decorate --reverse ${COMMIT}..

  It is more convenient (and less error prone) to just run that one command than to run that command and then run it again to pipe to ...| wc -l to get the patch/commit count. And if I mis-specified the "since" commit hash, the numbers in the summary lines make that obvious.

• Reviewing changes: When I'm reviewing somebody's changes, seeing "n of m" on them is a hint that the person has thought through the sequencing of the changes -- it is less likely to be "just a clump of changes". It's a small quality indicator heuristic.

  Though GitHub does not directly support a workflow in which commits can be reviewed in email, it does include the commit summary in the email messages it sends out. I, for one, prefer to read that first before reading the (potentially much longer) PR description. I think the "n of m" number makes the commit summary easier to digest. Here's what it looks like in the email message I received for this PR:

       -- Commit Summary --
  
         * [1 of 9]: filter::parse_spec(): add more parse_spec_global* tests
         * [2 of 9]: filter::parse_spec(): add more parse_default* tests
         * [3 of 9]: update docs to note that level names are case insensitive
         * [4 of 9]: markdown now shows 'RUST_LOG'; in bold (first mention only)
         * [5 of 9]: update crate-level docs to note non-env-var configuration
         * [6 of 9]: docs: clarify default enabled/disabled log level behavior
         * [7 of 9]: docs: show log levels in bulleted list
         * [8 of 9]: document 'OFF' pseudo log level feature
         * [9 of 9]: docs: term "logging directives" emphasized (first mention)

  When reviewing patches in email, seeing the collective "[PATCH n of m]" subject line would let the reader know at a glance whether they even have all of the pieces. This isn't a concern on GitHub, of course, but depending on how a commit series ultimately gets merged back into the main project there could be an analogous benefit when reviewing the Git history of a project (more on this below).

  Finally, if I'm on the fence about whether or not to go get a coffee refill before reviewing a series of commits, seeing "n of 27" nudges me toward a different decision than does "n of 3" :-)

• Commit history: The "n of m" messages make it easy to quickly inspect the 'git log' output while reviewing a pull request locally (e.g., after doing git fetch ${REMOTE_NAME} pull/${ID}/head:${LOCAL_BRANCH_NAME}). And that makes it easy to find the commit from which to start reading a la: $ git log -p --reverse d4606a33b38d..

  The "n of m" message are also useful when it comes time to merge the changes from a branch. There are different schools of thought on what types of merges to perform in different circumstances, but the "n of m" helps with a couple of common scenarios when doing a "recursive" merge (the Git (and GitHub) default):

  • If --no-ff (also the GitHub default) or --ff-only options are used, then the individual commits will live on in the Git history as independent entities. Having the "n of m" on the commit message shows that the commit was part of a broader context, which may be useful to consider when reading the commit history.

  • If doing a "Squash and merge", then the combined commit messages from the series will be grouped together in the "starter commit message" presented, which the person performing the merge will (typically) then massage (hopefully with the help of a good text editor, in non-trivial cases). In this content the "[n of m]:" tokens can be used within one's editor (assuming a programmable editor) to partially automate the task of editing the message. For example, they facilitate landmark parsing while building up an editing macro interactively.

[salewski]

@jplatte By the way, thanks for fixing the rustfmt issue!

[jplatte]

@jplatte By the way, thanks for fixing the rustfmt issue!

I only re-ran cargo fmt :sweat_smile: (although I would really prefer the formatting as it was too)

Also, why do your commit messages all start with [N of 9]:? I've seen this before but don't really understand what value it provides.

[...]

I was not expecting such an elaborate reply! Doing a lot of rebases myself I don't really get the benefits for that, but I can see how it would be nice to see when reviewing large change sets as a quick gauge for how far into the review one is.

I'll be doing the default GitHub "merge", i.e. with a merge commit, if that matters.

[salewski]

I was not expecting such an elaborate reply!

Yeah, I kinda got on roll there... :-)

I'll be doing the default GitHub "merge", i.e. with a merge commit, if that matters.

I generally prefer that , too, because it keeps a more perfect record of the already-massaged history.

I just pushed my rebased update. It's identical to the previous set with two exceptions:

• Commit 8is tweaked as we discussed above (for the "OFF" -> "off" changes)
• I added a commit 10 to the end to explain the use of lowercase for consistency, and that the handful of exceptions are not typos

Please take a look when you can. I'm happy to refine it further, too.