Project Status
I tend to only put projects on GitHub after they have reached a stable, usable state. On many projects, I do a fair amount of prototyping during the initial development. The first release is often not a gradual refinement of a single prototype. Rather, I often implement a number of separate prototypes, and one or more prototypes may contribute to the design used in the implementation of the first release. In this prototyping stage, I tend to use revision control for my own purposes, but the prototypes are eventually thrown away. In some cases, I write the release code based on what I learned from the prototypes and make incremental commits, while in other cases I start from a large “Add initial implementation” commit with the code from a final prototype.
There are a few positive aspects of this practice. Primarily, one can freely explore the design space without having to worry about creating a coherent commit history. It also prevents anybody from using an API that may be completely different in the release.
There are negative aspects of this practice as well. One is that not
all of the things learned during prototyping may be included in the
project history, such as designs that were tried and found lacking. This
is mitigated through documentation. While future developers may not be
able to browse the commit history of the prototype phase, they should at
least be able to read about what was discovered. In my projects, I
usually put project metadata into a project
directory, and
such prototype and design logs are written in dated Markdown files under
project/log
.
Another negative aspect is that progress during the prototyping phase is not made public. The largest drawback of this is that it is difficult to solicit feedback when the repository is not pushed yet.
I have decided to start making an effort to put personal projects on
GitHub earlier in the project life cycle. For new projects, I will try
to do so in a way that does not overly constrain exploration of the
design space. For example, I am thinking about using a single
prototype
branch that is merged into the
develop
branch when the design stabilizes. By experimenting
with all prototypes under a single branch instead of using a separate
branch for each prototype, even the commit history of the unused
prototypes will not be lost. By merging without fast-forwarding, it
should be clear in the commit history which commits are part of the
prototyping phase. Thought the commit history will include the prototype
phase, I will continue to write design logs in project/log
since an overview of what was learned is usually much easier to
comprehend than an early commit history.
The branch name should make it clear to others when the project is not yet stable, but I would also like to add a project status. I have been planning on doing this anyway, to indicate when a project is no longer actively maintained, but it is useful for the early stages of a project as well as the late stages. Searching for existing conventions, I found repostatus.org. The categories are not exactly what I had in mind, but I am happy to just use them!
I have added status badges to my public repositories on GitHub. They
show a color-coded status as well as link to short definitions on the repostatus.org website. (Note
that the commits are to the develop
branches and will not
show up on the main
branches until the next release of each
project.) I have also added status links to the projects page on this website.