-*- org -*-

#+STARTUP: hidestars oddeven

HINT: org-mode global cycling: S-TAB

HINT: To show all content (including any drawers), regardless of org-mode
startup visibility:

:    C-u C-u C-u TAB

[The above assumes the default key binding of TAB to [[elisp:org-cycle][org-cycle]].]


This is the 'NEWS' file for the 'ads-github-tools' project. This file contains
information on changes since the last release of the package, as well as a
running list of high-level changes from previous versions.  If critical bugs
are found in any of the software, notice of such bugs and the versions in
which they were fixed will be noted here, as well.

-----------------------------------------------------------------------

* ads-github-tools 0.2.0 (2017-02-26)

** fixes

*** issue 20: ads-github-merge-all-upstream: typo in log message ("a al" ==> "a la")

    https://github.com/salewski/ads-github-tools/issues/20

    Fixed typo in log message.


*** issue 21: ads-github-merge-all-upstreams: no longer chokes when it encounters a "detached HEAD"

    https://github.com/salewski/ads-github-tools/issues/21

    Prior to this fix the program choked (when the repo directory was
    initially in a "detached HEAD" state) upon attempting to restore the
    working directory to the state it was in prior to the program switching to
    the default branch. This happened because the code only knew how to deal
    with a working directory "attached" to a named branch. Since the repo was
    originally in the detached HEAD state, the program did not have a named
    branch to which it could switch back.

    Rather than attempt to switch back to an explicitly named branch, the code
    now basically does this:

    :    git checkout @{-1}

    which you can read as: "where HEAD used to be one move ago (before we
    checked-out the default branch)".

    The impact of the original problem was that the
    'ads-github-merge-all-upstreams' program stopped dead in its tracks and
    left the repo directory with the default branch checked out.

    The workaround was to simply re-run the program leaving that repo with the
    default branch checked out. Because the program then found the repo with
    the default branch already checked out, it did not attempt to swicth the
    branch, so also did not need to attempt to restore it to its original
    state. Once the program completed, the user could then manually check out
    the tag (or whatever) to then put the repo back into the original detached
    HEAD state (if so desired).

    With this fix, such workarounds are no longer needed.


** improvements

*** issue 19: ads-github-merge-all-upstreams: avoid using 'git branch' porcelain command

    https://github.com/salewski/ads-github-tools/issues/19

    Replaced three invocations of the git porcelain command 'git branch' with
    (as appropriate) invocations of git plumbing commands:

    : git symbolic-ref --short --quiet HEAD

    or:

    : git for-each-ref --format='%(refname:short)' 'refs/heads/'

    or:

    : git for-each-ref --format='%(refname:short)' 'refs/remotes/upstream/'


*** issue 22: ads-github-fetch-all-upstreams: add feature to detect and pull down only "missing" repos

    A '-m' (--missing-only) command line option has been added to the
    'ads-github-fetch-all-upstreams' program. This new option provides a
    shorthand way of invoking:

    :    $ ads-github-fetch-all-upstreams -c <MISSING_REPO>...

    while at the same time limiting the program's behavior to /only/ missing
    repos. And it does so without the user having to explicitly name (or even
    know) the values for each missing repository name.

    In this context, a "missing repository" has the same meaning as it does
    for the '-c' (--clone-if-missing) option. That is: any repository from
    GitHub where the local git working directory is not present.

    The following is the equivalent invocation of the above:

    :    $ ads-github-fetch-all-upstreams -m

    The semantics of:

    :    $ ads-github-fetch-all-upstreams -m <REPO>...

    limits the operation of the program to only those explicitly named repos, and
    will clone them only if they are missing (that is, the program will not fetch
    changes from the corresponding upstream repo when the local repo is already
    present; see "Design Notes" section below for more on the rationale for this
    behavior). If any of the explicitly named repos are already present, then the
    program will print an error message and exit with a non-zero status at the end
    (after cloning all of the other explicitly named repos (if any)). This is
    intended to make the user aware of any repo names fat-fingered on the command
    line.

    Note that the '-m' (--missing-only) option implies '-c'
    (--clone-if-missing), so the '-c' in the following is redundant (but
    innocuous):

    :    $ ads-github-fetch-all-upstreams -m -c

    Said another way, the '--missing-only' option limits the behavior of the
    program to operate /only/ on repos that are missing, so the behavior of
    the program when '--missing-only' is specified is meaningless unless
    '--clone-if-missing' were also implied.

**** Design Notes

     The author considered making the semantics of the '--missing-only'
     option, when provided with explicitly named repo names on the command
     line, be "fetch (or clone) these particular repos plus any repos that are
     missing".

     That approach would be consistent with the behavior of:

     :    $ ads-github-fetch-all-upstreams -c <NONMISSING_REPO>...

     insofar as the repos would be cloned if they were missing, but fetched
     otherwise. That idea was ultimately rejected because it would fetch
     updates for the repo if its working directory happened to be
     present. That's not "missing only" behavior, so would make the behavior
     of '--missing-only' (or whatever the option would be named) more
     difficult to explain and comprehend. It's also not the common case itch
     being scratched.

     This decision does mean, though, that there is currently no way to express
     "fetch (or clone) these particular repos plus any repos that are missing" when
     one or more of the explicitly named repos is already present, yet still have
     the program exit with a zero exit status. This use case can, of course, be
     easily accommodated by using two separate invocations of the program:

     :    $ # first clone (as fast as possible) any missing repos...
     :    $ ads-github-fetch-all-upstreams -m
     :
     :    $ # ...and then fetch changes for explicitly named repos (note no need for '-c' here)
     :    $ ads-github-fetch-all-upstreams <REPO>...

     The second invocation in that example will be an elaborate NOOP when all of
     the explicitly named repos were freshly cloned by the first invocation.

     If this example represents your common use case and you find this behavior
     limiting or otherwise annoying, please contact the author as outlined in the
     [[https://github.com/salewski/ads-github-tools/blob/master/BUGS][BUGS]] file.


*** issue 23: ads-github-fetch-all-upstreams: only one unprocessed named repo noted in error message

    https://github.com/salewski/ads-github-tools/issues/23

    In the version of `'ads-github-fetch-all-upstreams'` shipped with
    `ads-github-tools-0.1.1`, when a user fat-fingered more than one repo name
    on the command line, the program printed an error message that named only
    the first unprocessed repo name that was detected.

    The current version of the program improves on that behavior to name /all/
    unprocessed repo names. This gives a better indication to the user about
    the size of the error, and also gives the user the opportunity to correct
    all such errors at once (rather than playing whack-a-mole fixing one at a
    time and having successive runs of the program fail on the remaining repos
    that were not named in the error message).


* ads-github-tools 0.1.1 (2016-09-26)

** fixes

*** issue 17: ads-github-merge-all-upstreams: stderr message on failed ff merge indicates "bailing out", which is not always true

    https://github.com/salewski/ads-github-tools/issues/17

    In the version of 'ads-github-merge-all-upstreams' distributed as part of
    ads-github-tools-0.1.0, the tool would emit an incorrect "bailing out"
    message when the tool's '-k' (--keep-going) option was speecified and a
    fast-forward merge is not possible for some reason:

    :    $ ads-github-merge-all-upstreams -vkpp
    :    ...
    :    ads-github-merge-all-upstreams (info): [repo: "foobar"] currently checked-out branch ("master") is the default branch (no need for checkout)
    :    fatal: Not possible to fast-forward, aborting.
    :    ads-github-merge-all-upstreams (error): [repo: "foobar"] was error while attempting to merge 'upstream/master'; bailing out
    :    ads-github-merge-all-upstreams (warning): '-k' (--keep-going) specified; continuing
    :    ads-github-merge-all-upstreams (info): [repo: "bazqux"] currently checked-out branch ("master") is the default branch (no need for checkout)
    :    Already up-to-date.
    :    ...

    That message is correct for the default behavior of the program (when the
    '-k' option is not specified, but when the '-k' option /is/ specified, the
    message should not have indicated that the program was "bailing out"; it
    was not correct, and gave the impression that the error detection is not
    working correctly.

    The program has been fixed to emit "context aware" messages in these
    scenarios. With the default invocation (no command line options specified)
    is the same as it was previously:

    :    $ ads-github-merge-all-upstreams
    :    ...
    :    fatal: Not possible to fast-forward, aborting.
    :    ads-github-merge-all-upstreams (error): [repo: "foobar"] was error while attempting to merge 'upstream/master'; bailing out
    :
    :    $ echo $?
    :    1

    When the '-k' (--keep-going) option is specified, the error message
    related to the failed fast-forward merge no longer indicates that the
    program is "bailing out":

    :    $ ads-github-merge-all-upstreams -k
    :    fatal: Not possible to fast-forward, aborting.
    :    ads-github-merge-all-upstreams (error): [repo: "serverless"] was error while attempting to merge 'upstream/master'
    :    ads-github-merge-all-upstreams (warning): '-k' (--keep-going) specified; continuing
    :    ...
    :    ads-github-merge-all-upstreams (error): one or more errors encountered with '-k' (--keep-going) specified (see error output above for details); bailing out
    :
    :    $ echo $?
    :    1

    Note that the error message from the 'git merge --ff-only ...' command
    invoked internally still indicates that it is "aborting". We hope that it
    is clear from context that that is not coming directly from the
    'ads-github-merge-all-upstreams' tool and that users are not confused by
    it.


*** issue 18: ads-github-merge-all-upstreams: suppress "no upstream changes to merge" messages unless verbose output requested

    https://github.com/salewski/ads-github-tools/issues/18

    The default output of the 'ads-github-merge-all-upstreams' program (that
    is, when the program is invoked with no command line options) was
    previously too chatty; it was emitting a bunch of "no upstream changes to
    merge" messages:

    :    ...
    :    ads-github-merge-all-upstreams (info): [repo: "foo"] no upstream changes to merge, and "aggressive push" (a al '-p -p') not specified; skipping (okay)
    :    ads-github-merge-all-upstreams (info): [repo: "bar"] no upstream changes to merge, and "aggressive push" (a al '-p -p') not specified; skipping (okay)
    :    ads-github-merge-all-upstreams (info): [repo: "baz"] no upstream changes to merge, and "aggressive push" (a al '-p -p') not specified; skipping (okay)
    :    ...

    The program now only emits those messages when the user requests verbose
    output via '-v' (--verbose) option.


** improvements

*** issue 16: ads-github-merge-all-upstreams: use 'git push origin heads/<BRANCH>' to avoid ambiguity with tags of the same name as <BRANCH>

    https://github.com/salewski/ads-github-tools/issues/16

    If a repository had a tag name that matched the default branch name
    (typically "master"), then the previous version of the program would not
    be able to push the merged changes to the origin repository because the
    git refspec used internally was ambiguous. The program has been enhanced
    to qualify the default branch name as "heads/<BRANCH>" rather than just
    "<BRANCH>" to remove this ambiguity.


* ads-github-tools 0.1.0 (2016-08-20)

** Initial version of project. The project currently provides five command line programs:

   + ads-github-normalize-url

     Produces a "normalized" view of a given URL, suitable for use in
     generating an ID. Currently is a quick 'n dirty implementation optimized
     for this sole purpose, so there's no guarantee that the normalized
     variation of the URL will actually work

   + ads-github-hash-url

     Similar in spirit to 'git-hash-object(1)', this tool takes a (presumably
     normalized) URL and emits a checksum for it. Currently uses the SHA-3
     256-bit algorithm variant.
  
   + ads-github-show-rate-limits

     Shows the user's GitHub API rate limits ("core" and "search").

   + ads-github-fetch-all-upstreams

     Operates on the working directories of a collection of GitHub-hosted git
     repositories. The user can specify one or more repositories explicitly to
     restrict operations to just those repos. Each that is found with an
     'upstream' remote defined will have 'git fetch upstream' invoked in it.
  
     - With the '--clone-if-missing' option, any of the user's GitHub repos
       for which there is not a git working directory beneath the current
       location will be cloned (using the 'git-hub' tool's 'clone' operation,
       which sets up the 'upstream' remote if the repo is a fork).

     - There's also an '--upstream-remote-if-missing' option that will add the
       'upstream' remote on existing project working directories that do not
       have it (only if the project is a fork of another project, of course).
    
   + ads-github-merge-all-upstreams

     Operates on the working directories of a collection of GitHub-hosted git
     repositories. Each that is found with both 'origin' and 'upstream'
     remotes defined will have:

     :    git merge --ff-only upstream/<DEFAULT_BRANCH_NAME>

     invoked in it. The user can specify one or more repositories explicitly
     to restrict operations to just those repos. The program is careful to
     sanity check the local repository before attempting any operations on
     it. Also, it will skip any repository for which the git index has any
     changes recorded. Will (temporarily) check out the default branch before
     merging (if the working directory happens to have some other branch
     checked out); will restore the originally checked out branch when done if
     the temporary switch was necessary.

     - With the '--push' option, will invoke:

       :    git push origin <DEFAULT_BRANCH_NAME>

       for each repo.
