+++ categories = ['thinks'] date = '2021-01-03' description = 'roadmap and changelog file' slug = 'roadmap-to-changelogs' title = 'The Roadmap to Changelongs' +++
Something we have all experienced is the problem of accurately conveying intent forward to future co-workers for discrete components of a system.
I'm sure you're familiar with this story:
Your well considered component at an early stage startup, perhaps a small service, perhaps a library, makes pragmatic concessions due to time constraints. You craft it well with forward-looking interfaces abstacting the compromises you've had to make to get to launch.
Twelve months later your team has grown significantly from five to fourty-five and a 'feature team' is tasked with advancing the prospects served by your well meaning component. After a code-review the new developers agree your component was short-sighted and unsuited for the brave new world of tomorrow and it gets re-written from scratch. (sad-face)
Perhaps you overhear a conversation at lunch, and protest, 'But that service was designed to be extended this way, I had fully intended on adding {feature} which is why those interfaces were there in the first place!' .. Alas you are too late, your good intent and excellent abstractions were not only ignored, the effort you took in making them, having not been realised has become a historic waste of your time.
After suffering the ignomity if this more than once in my 20+ year career I decided it was a problem I wanted to fix, and I'm please to say that I did and the system I've adopted has been successfully applied to a number of teams I have worked with. At the request of one of my cohort I am documenting it here so they can share it with others.
The problem stems from our inability to convey good intent in the face of constraints in a meaningful way that lives along-side our code in a visible manner.
To rectify this I developed an approach which has saved myself and the teams I work with much time and rework. This is simply the act of combining two kinds of lists in our README or even inline as comments, a forward looking roadmap and a backward looking changelog.
# Roadmap
- [ ] Consider merging this with the Asset service, they are always accessed
together anyway
- [ ] Introduce cache layer
- [ ] Implement Postgres store when the PG cluster is ready
# Changelog
- [x] Implemented SQLite store (14/05/2020 - @tjstebbing)
- [x] Added store interfaces, abstracted database because we're moving to
postgres in a few months (12/05/2020 - @tjstebbing)Without much effort we can introduce a new section above our Changelog that immediately conveys the intended next steps for this service. With a quick skim over the Changelog and Roadmap anyone new to this service can see why it behaves as it does currently, and how it intends on moving forward in the future.
Even if a new owner decides they want to throw away the roadmap because things have changed, at least they can do so with understanding, and you good engineer will sleep better knowing that your effort has not been for naught.