pulsar-edit
New ChangeLog Format
I really do think keeping a changelog is important, but with how many moving parts there are it can be difficult to keep track of everything. That's why I propose instead of having to keep track of either ChangeLogs in each repo, or just reading through PR's of each repo, once we start releasing updates our life may be easier to have a single ChangeLog to documents the changes that the editor will experience.
Now repos that do not effect the change log don't have to be listed here, things like our Backend, and Website and such, but for Core packages I feel it makes sense to keep everything in one place.
While originally I wanted to base this off recommendations from Keep a ChangeLog I found they didn't really suit our needs, so modified it a bit.
For me at least, this new format makes it easy to find what has changed in each repo, while importantly giving credit to everyone who works on this project in an easy to see place. Additionally having a changelog like this allows us to easily find what has actually changed since we've taken over, and in the future what has changed per each version release.
If this format looks good I can link the top header to a document on our Org repo detailing how to continue writing in this format, and why each choice was made. But beyond that for anyone reviewing here's a short summary:
The top header gives some details about our ChangeLog and practices it follows.
Below that the [Unreleased] section will update to whatever our first version release is after it's done. Similar to "Keep a ChangeLog"s format.
Then right below it is our biggest changes. Mostly for end users to see what they should care about in this release.
Then below are the details of what's changed per each repo. The repo starting with ### and the changes below it, denoted by what kind of change Fixed, Bumped, Added, Removed.
Even more though there can be categories of changes, such as changes that were done by many contributors but isn't defined by a single feature. Things like Rebranded, Decaffeinated, and Tests.
Please let me know what you think. And if we do like this style, I'd propose each PR adding it's changes to the change log, that way we don't have to always keep it updated ourselves (unless of course it's a change in another repo), then once we are close to a release we can go through and pick out the biggest changes to end users to feature at the top.
I'm very much on board with this. So the changelog just continues to grow in size with each release just moving stuff further down?
Have we given thought as to how this works within Pulsar? I know there was a plan to add the changelog to the welcome package - I assume this would be making a subselection from this log or would it still be manually moving bits from here to there?
We would also need to look at editing https://github.com/pulsar-edit/pulsar/blob/6d265c675576d9324c1759989153240b31c51c9f/packages/about/lib/update-manager.js#L117-L139
I mean it will need changing anyway but this currently directs you externally, would we want to keep that kind of thing or just call the changelog panel from the welcome package?
@Daeraxa for your first point, yeah I imagine it'll just keep growing in size as much as needed.
And for the welcome package it'd be awesome if it could read from the file automatically, and maybe that could be done, but I also don't think it's to much trouble that when we find a releases 'highlights' that those can be added to the top of the ChangeLog, added to the welcome package, then finally maybe used for the release notes on GitHub. Just my two cents.
As for those external links, I think letting those still speak for themselves, linking externally, but maybe instead to our site, which could import the changelog here? Just to display it on the website cleanly?
But then with the welcome package having a dedicated ChangeLog button. That at least makes sense to me
And an edit for linking to our website, with the importing ChangeLog file from here, the links shouldn't be hard to autogenerate if we make sure those Second level headers of the ChangeLog are exact version matches, because in the editor to link to an external ChangeLog we can just say https://pulsar-edit.dev/docs/ChangeLog#v1.0.0 or whatever it is
Something to be aware of as well, we can make a GitHub Action(s) to generate/update our changelogs, and should
Removing the manual effort of keeping that updated is a rather high priority
As for those external links, I think letting those still speak for themselves, linking externally, but maybe instead to our site, which could import the changelog here? Just to display it on the website cleanly?
Thats a good point, it definitely makes sense to have the website version still, easy enough to include. Maybe we could have the "full" and "release" changelog both included? One would just be pulsar/CHANGELOG.md and the other would be the curated "app" version.
For reference, I love the way Nextcloud write there CHANGELOG. First part is TLDR; so a user can see fast what "he want to know". And after, there're automated PR merged.
I would like this pattern:
^# (?>.+)\n(?>\n- .+)+\n\n\n(?>## (?>.+)\n(?>\n- .+(?>(?!:).|:\n \* .*(?>\n \* .+)*))+(?>\n\n### .+(?>\n- [A-Z][a-z]*: .+(?>(?!:).|:\n \* .*(?>\n \* .+)*))+)*(?>$|\n\n\n))*$
Is that ok? (I will describe that when I have time. Regex was quicker)
Edit: fix regex Edit2: title can be anything Edit3: improved regex by disabeling backtracking Edit4: require non-empty messages/headings
We should put the Pulsar version under ## [Unreleased]
## [Unreleased]
...
## Pulsar Version 1.0.0 (2022-11-21)
...
### ppm
...
### autocomplete-html
...
### settings-view
...
## Pulsar Version 0.0.1-alpha (2022-11-21)
...
I think that is the implication, if you look the very bottom one is a link to Atom and @confused-Techie confirmed what I thought which was that the log just grows upon each release.
i.e. stuff is added to [unreleased] then on release the version is added and we start a new [unreleased] section at the top again.
We should put the Pulsar version under ## [Unreleased]
## [Unreleased] ... ## Pulsar Version 1.0.0 (2022-11-21) ... ### ppm ... ### autocomplete-html ... ### settings-view ... ## Pulsar Version 0.0.1-alpha (2022-11-21) ...
The reason I haven't included a version is because we don't know what it is yet. My idea was that once we say, okay all of our work has been to 1.0.0 or whatever it is, we change where it says Unreleased into 1.0.0 and create a new section above it called Unreleased.
Otherwise if we are adding a non-existant version it might be confusing
Is there anything helpful we could put in PR titles etc. that make filtering for things easier?
I would like this pattern:
^# (?>.+)\n(?>\n- .+)+\n\n\n(?>## (?>.+)\n(?>\n- .+(?>(?!:).|:\n \* .*(?>\n \* .+)*))+(?>\n\n### .+(?>\n- [A-Z][a-z]*: .+(?>(?!:).|:\n \* .*(?>\n \* .+)*))+)*(?>$|\n\n\n))*$Is that ok?
(I will describe that when I have time. Regex was quicker)
So I will try to explain what the regex does.
First there is a header at the top of the file. It starts with # Changelog the after 1 blank line there is a list of the general informations all starting with- . At the end of the header 2 blank line.
Then the versions start with always 2 blank lines in between. The heading of each version starts with # . After the heading is a blank line and than an overall summary of the big changes in form of a list all starting with - . It is possible to have a sub list when your line ends with :. The sub list lines start with *.
In a version there are more percise informieren for each sub project like for example packages. They are separated with 1 blank line to the changes overview and are seperated by also 1 blank line. Their heading starts with ### . After the heading is no blank line! The changes are listed similar to the changes overview. The difference is that each change has to start with a verb like Fix, Remove or Decaffeinate. It has to start with an uppercase letter and it has to be one word. It is directly followed by a :. After that there should be at least 1 space and if possible indented like the surrounding changes.
This is my suggestion. I make the rules that strict to make parsing and validation easier.
Is there anything helpful we could put in PR titles etc. that make filtering for things easier?
This discussion is becoming a bit more than I had anticipated, let me take a second and get a proper discussion going. Because if we want to try and automate this whole process, I love the idea, but exactly there needs to be helpful titles to automatically grab things as well as we will need to determine how we collect the information from other repositories. Give me a few moments. But I love all the ideas from people here
I've gone ahead and started a discussion to better format our ideas
@Daeraxa @GuilleW @Sertonix @Spiker985
@pulsar-edit/documentation Do we think this one is good to merge? Especially now as we are moving towards adding most if not all of our core dependencies to the core itself, the whole conversation of managing changelogs across dependencies has become kinda moot.
Then for anything that isn't in the core, it's changelog shouldn't be here either
Honestly I thought this was already in, definitely has my blessing.
When you say anything that "isn't in the core" do you mean packages on the repo like teletype that are entirely optional but under the org or do you mean core packages that aren't in pulsar/packages?
I think anything that is bundled in as a core package of the application, regardless of where it currently is, should be on the changelog. Anything that is an optional install should not be and should have its own.
Honestly I thought this was already in, definitely has my blessing.
When you say anything that "isn't in the core" do you mean packages on the repo like teletype that are entirely optional but under the org or do you mean core packages that aren't in
pulsar/packages?I think anything that is bundled in as a core package of the application, regardless of where it currently is, should be on the changelog. Anything that is an optional install should not be and should have its own.
Yeah by core I mean purely anything in packageDependencies otherwise items that the editor loads during it's startup.
So yeah we are on the same page there.
But with your approval I'll go ahead and clear the conflicts and update this file with the new entries then merge
Like discussed I'll go ahead and merge this PR.
In an additional PR, I will add the missing data to it as well as link to a guide about how to write and format such a change log for easy consumption and added of others.
Although in the future, it may be a good idea to ask users to add to it, or we periodically work to add missing commits to the document