Private Solutions with Git

Section 37.3 Private Solutions with Git

(2020-06-06) We no longer advocate this approach, and find Section 37.2 easier and more robust. This section is no longer maintained and may be removed.

Suppose an author distributes a textbook with an open license, and so makes the PreTeXt source available publicly (perhaps as a condition of the license). Perhaps the author also intends <hint> provided with <exercise> to assist students, and having them available as knowls in HTML output is a great way to make them easily available, but not immediately visible. But the author has also written some, or many, <solution> for the <exercise>, but these are only meant for instructors, and not for students. See the discussion at Section 36.1 for more background.

One approach is to distribute an Instructor Version or Solution Manual only on request, and only as a PDF. The ability to provide a watermark on every page (see Section 26.5) allows you to include a personalized message such as

Issued to Charles Darwin.  Do Not Copy.

It would be a trivial technical exercise to remove this, but perhaps the moral imperative (in an extra <preface> as well?) would dissuade most from distributing further?

But what about publicly available source code? After several unsatisfactory experiments, we have arrived at the following solution. Again it involves an intermediate understanding of the revision control software, git. And again, this is an outline.

Create a private repository for authors, and other trusted contributors. In other words, if shared, read access is controlled via passwords or something similar.
Create a branch off of master called solutions.
Do all editing of private material, and only editing of private material, as commits to this branch. So a typical commit might just be <solution> elements inside existing <exercise>. Any script or top-level file for producing a solution manual might also be part of this branch.
Do all authoring in this private repository, mostly as commits on master.
Periodically, while the solutions branch is checked out, merge master to bring in new changes to the main content.
Never ever merge solutions into master. In other words, solutions is a long-lived branch which never dies and is never merged into another branch. (Never rebase this branch if you have collaborators sharing the private repository.)
Push and pull both master and solutions to and from the private repository by setting up tracking branches.
Create a public repository which is a strict duplicate of the master branch. Periodically push the master branch of the private repository to the master branch of the public repository. Only. Its only purpose is for the next item. Use commands or a setup which makes it impossible to accidentally push solutions to this public repository.
The commits in the public repository will be identical to those on master in the private repository. So anyone can clone or fork this repository and make pull requests, which authors can apply and mange via the private repository. But solutions will never be part of the interaction with this repository.

Prev Top Next