automating changelogs, git workflows
so i wanted to get advice on both topics
automating changelogs
How do ya'll usually deal with this? I specifically want to automate/semi-automate changelogs for our users/client to see. We/I already use semantic commits.
For the documentation tool itself, found out about fumadocs, but the automating of changelogs part is something im not sure how to go about
git workflows
I have a bit of confusion about this. For background, im looking for a relatively simple git workflow.
I used to do something like having a main and a dev (which i use as a staging environment) and i branch off of dev to create feature branches, merge them back to dev, do some automated and manual testing on the dev/staging environment before merging back to main.
However, ive recently come across TBD which seems to espouse short-lived feature branches and directly branching off main, which I liked for how simple it is and minimizes merge conflicts.
However, it seems like the new complexity that arises with this is that this will require preview deployment links in place of a staging environment, which is all fine and all since coolify has this (I don't use vercel/netlify).
But one major PITA that I've found with this workflow is having to rework my authentication to work with dynamically-generated preview links (in particular google's authorized and callback URIs).
So I'd like to get some advice on this as well
(3). some sort of ai tool for automating/syncing documentation with code
ya'll have any suggestions for this? keeping code documentation in sync with the actual code is kinda a PITA. there's coderabbit, cursor bugbot but those are heavily tailored for code reviews afaik
Stack: React + Typescript, Coolify/VPS
4 Replies
The right Git worklow really depends on what your doing and the team your working with
small team 2-4 people, we prefer fast iteration/feedback cycles but a staging environment is still nice (i.e. being able to test changes before merging to main)
In my experience changelogs can not be truly automated. In the end they are indented for human consumption and any automatic data source just doesn't work.
I typically keep 3 changelogs:
1. For developers - this is generated from semantic commits, using keep a changelog scheme,
2. What's new file, that is manually updated by developers with any notable changes (i.e. as part of a PR). Bug fixes do not count.
3. Manually crafted changelog on each release, mostly based on the what's new file. Sometimes it also integrates bugfixes, then that is taken from the developer changelog, since it has the list of all tickets that were resolved.
For 3 - depends on the kind of documentation.
1. Developer docs - I have those in line in code, so they are always in sync.
2. Software architecture - every single item has an ID, those IDs are also added to code. If the code you're touching has an ID attached - you do not change it, unless it is in the same PR that changes the architecture document or you are fixing a bug (i.e. code did not work as architecture specified)
3. Requirements / use cases / user stories (whatever you need/use) - every single item has and id that is then referenced in software architecture. Test cases also link to those.
As far as tooling goes, I actually keep 2 and 3 in Enterprise Architect, I export data from code regarding the linked IDs. That allows me to do cool things, such as find use cases that are not implemented in code. Or quickly check which use cases would be impacted if I changed something in the implementation or architecture.
Note that I generally do not model code (i.e. the thing they teach you in univeristy when they pretend to teach you UML), i.e. I do not draw out the functions, classes or specific data members (unless that is important for some reason, ex. it's external interface).
This has been working for me for the part 7 years, in projects that I do as a solo contractor, in projects where I had to hire a couple people to help with and in my day job (well, here for the past 3 years, since I convinced them to try it).
Thanks! i'll take the time to read through this