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.