As you may have seen I recently created a post asking for ways to increase the Bus Factor of a project.
There were some great responses and it prompted my team to adopt a process where when submitting a code review you select all the other developers as reviewers (not every developer has to approve the request though as this could get tiresome). This should help with knowledge sharing across projects and developers within the team.
A common, and related problem amongst teams of developers working on a project together is keeping everyone in the loop when something changes within the project, be it a code, design or devops related change.
A possible solution I've thought of is sort of a changelog, but for developers not end users. The idea being that there would be a changelog.md file in the root of each project which gets updated whenever a feature is merged to the master branch. The message should be simple but convey anything that may be relevant for a future developer to understand.
For instance, recently a developer made a change to our docker setup and updated the readme.md to reflect this change, however upon picking up the project to add a new feature I didn't check the readme.md and my environment wouldn't work. Rather than looking through commit history or disturbing another developer I could simply have looked at the changelog.md file and seen the following:
31/07/2018
- Now use docker-sync for handling storage in project, details of what you need to change in README.md
This simple message tells me all I need to know before I pick up the project again and get involved. This could be seen as duplication of commit messages but i often find commit messages offer quite technical details of what has changed which isn't always important when you are just jumping back into a project, especially if you aren't touching the part in those commits, however it can be handy to get a one sentence overview of what has changed in more of a high level way.
A colleague showed me this and it seems like this is spot on with what I had in mind: https://keepachangelog.com/en/1.0.0/
What do you think?
Top comments (11)
I'd focus on improving your commit messages. They should offer a relatively high-level overview of a change, and with git you can add more detailed information on subsequent lines as needed. If your messages lead with technical minutiae, it's going to be difficult to parse useful information from them no matter the situation. A developer-focused changelog is a duplication of effort that nobody's going to want to spend time on.
I do agree with what you are saying regarding commit messages however I think the developer changelog.md file would sit somewhere between commit messages and a user friendly changelog. For example:
Commit messages may be:
But the changelog.md file would say:
Probably a bit of a weak example but it strips out the stuff that a developer doesn't need to worry about such as simple fixes, typos, merge commits etc. which just pollute the commit history when you are looking through for changes that either need action (environment changes) or are worth knowing about (rather than opening a file and wondering why functions have been removed/changed significantly etc.).
Maybe every merge/commit to master is a bit excessive as they may not all require the developer to be aware of the change (typos etc.) but I still think it has its merits.
Yeah, I see room for improvement in your example commit messages honestly:
"Refactor for tab issue fix": what fix? That could at least reference the commit number of the fix, or summarize it if that's possible without getting too verbose.
"Use calc to set width minus gutter": where? You answer this question in your changelog but it would be even better in the commit message. It's useful information no matter what.
The third is fine and your corresponding changelog entry is basically just changing the order of the words around. Overall, you're going to get tired of updating the same information in two places quickly, and you'll also likely find yourself hunting through one when the information you need is in the other. Making exceptions for certain "low-risk" commits is not something you can do consistently so it's guaranteed to let some useful information slip. Being more thorough with your commit messages (even better, using something like the conventional commit specification) will prevent the headaches of log duplication, and if you want a tidily organized summary there are tools like standard-version to generate them without the extra manual overhead.
All very good points,I think the reason the commit messages may seem vague is because we have the issue reference in each commit so 'refactor for tab issue' will be the tabs related to tsk020 which may be in JIRA as "change layout on gallery page to be responsive" or something, so the message is within that context, again probably a weak example. I think you're also right about not having the motivation to continue updating it, it may be fine for the devs we currently have for a while but as devs come and go and time goes on it will probably end up outdated. Hmmm
Is there a reason why it needs to be its own document? Especially if you're referencing stories/tasks in git messages.
If someone wants to read the reason why there was a commit they'd check the task which was tagged tsk020 in this case. Each of the changelog items "Gallery width now dynamic", "Menu button hidden on print" could be their own task, and the commits would be prepended with tsk021, tsk022 respectively. The branch would be named something like "feature/tsk020-change-layout-on-gallery-page".
Also when I'm opening a pull request I usually list out the changes. It's useful for yourself to see if you've filled the criteria of the story and also when someone is reviewing, they know what they're looking at and looking for. We delete branches after they are merged, but the PR doesn't go anywhere if anyone wants to go back and reference the changes.
The point of the changelog would be for when a developer comes back to a project after a while they can simply view the developer changelog as a way of saying 'what do I need to do and know to get my environment working and get up to speed'.
For example, "db now hosted on AWS" may be a part of the dev changelog but won't fit in to a git history. Now I know that if I need to access the DB I login to AWS rather than the previous service.
I agree that a task based changelog would be largely redundant, I think I'm still in the process of figuring out exactly what would be in the changelog to be honest but things like the example above would be super useful to store in one single place rather than the last dev to work on the proejcts mind. I think environment/third party services changes would be the main use for this file.
I used to do this in the dark days before I learned git and it was terrible because I updated it every few "work sessions" and skipped half of the things I did. This was a process issue, not with the idea itself though.
I think there's a place for something like this, as information is scattered so wide. You have commits on feature branches that might be descriptive, but they're often squashed and you lose context. There's issues and stories in your task tracker of choice but those cards get migrated through the various states of completion before being archived and you all move on. Basically we generate lots of information as we move forward but that information isn't inclined to move with us.
It requires a little bit of upkeep but for providing a running record of high level, meaningful changes but it sounds useful. This is about features, not implementation details. I think it should go like this:
This isn't a perfect idea but I think there's merit in something like this. It's also accessible to people other than developers. You don't need to traverse a git commit graph to catch up on what's been happening.
Totally agree about issues in the issue tracker being lost over time. Once issues leave the kanban board I never see them again. Going back through the commit history is fine if you are looking for a specific commit or when a specific file changed but when you are just trying to catch up on anything that is actually critically relevant to how you approach a new feature it's not always clear what is actually useful and what is just noise.
I see it as not a comprehensive list of every single feature that has been completed on the project but more of a living readme.md. It's a place where a developer can go to see what technical points have changed that they may find useful. This may or may not be tied to an issue within your issue tracker.
Another few examples:
- We switched to user token flow from app token flow so we get access to user endpoints, this includes adding user auth/login interface- Moved storage to AWS bucket so we don't use /storage anymore, see uploadController.php for example of how it's used- Started using Redis for session management due to load balancer being implementedThese are things which you could decipher from the commit history but this is a much more easily digestible format for only stuff that actually may require a developer to change their approach when adding features or refactoring code.
The more I think about it the more I don't think it's wise to enforce it for every feature as some features are trivial enough that they won't effect a developers approach. For instance adding a new route to a simple page may not really change a developers approach to any new features so not really necessary to go into the changelog.md
Great idea. Read me can be helpful. I find other developers tend to leave more of the whole story and context of changes which are really helpful, but commits are more technical yeah. People just leave the technical change. Maybe we should change the way we describe commits as if it's being communicated to an end user
Some of the examples remind me of guidance for commenting in code i.e. focus more on 'why', less on 'what' or 'how'.
Commit messages should have related/closed issues/bugs, but they could also have the 'why' messages you mention. I am wary of introducing more places to forget to check.
Maybe some sort of markdown in the commit logs to distinguish procedural issue tracking from useful commentary?
I've been pondering your idea for a while, and found an example of a repo that has a changelog. Check it out to see how they structure it:
github.com/winstonjs/winston/blob/...
Maybe a good idea!