Replies: 4 comments 8 replies
-
|
Here are the change logs (markdown) that are generated for Patch from the yaml files.
The yaml files can be changed retroactively to optimize them in case of follow up changes, as long as there was no public release. For game code I think it does make sense to track somewhere if a particular change was replicated in Generals code (or in Zero Hour code) if it would apply. |
Beta Was this translation helpful? Give feedback.
-
|
I don't disagree that keeping files of changes is a good idea, but if we could generate them automatically instead of having to write both a PR and a yaml file. This is why I really try and advocate for a commit standard, as the files can then be generated when the PR is merged. |
Beta Was this translation helpful? Give feedback.
-
|
I am all for encouraging change log generation on commits. Makes it easier for contributors to see it. Perhaps there can be an option to opt-out of auto change log generation when a change does edit an exisiting change record or manually creates a new one. |
Beta Was this translation helpful? Give feedback.
-
|
I don't think i understand what you mean. Should changes made to an existing commit not update the yaml? Or would i depend on whether the other change already has been pushed. |
Beta Was this translation helpful? Give feedback.
-
|
Commits cannot be updated. If the change log script is inflexible, then every new commit will simply create one new change log entry. |
Beta Was this translation helpful? Give feedback.
-
|
@Generalcamo showed me a repository for BYOND that has an automatic changelog system. Their way of doing it is to allow people to write whatever they want in the PR. But if they want the change to be logged in the changelog file they add a block like so: There can be multiple authors and tags, depending on what changes was made. Which will give the following output .yaml (Copied from Baystation12) 2013-01-07:
Cael_Aislinn:
- tgs: Updated server to tgstation r5200 (November 26th, 2012)
Chinsky:
- rscadd: 'Implants: Explosvie implant, exploding when victim hears the codephrase
you set.'
- rscadd: 'Implants: Compressed Matter implat, scan item (making it disappear),
inject yourself and recall that item on will!'
- rscadd: Implant removal surgery, with !!FUN!! results if you mess up it.
- rscadd: Coats now have pockets again.
- rscadd: Bash people on tabetops. an windows, or with stools. Grab people to bash
them on tables or windows (better grab for better hit on windows). Drag stool
sprite on you to pick it up, click on it in hand to make it usual stool again.
- rscadd: Surgical caps, and new sprites for bloodbags and fixovein.
- rscadd: Now some surgery steps will bloody your hands, Full-body blood coat in
case youy mess up spectacualry.
- rscadd: Ported some crates (Art, Surgery, Sterile equiplemnt).
- tweak: Changed contraband crates. Posters moved to Art Crate, cigs and lipstick
ot party crate. Now contraband crate has illegal booze and illicit drugs.
- bugfix: Finally got evac party lights
- bugfix: Now disfigurment,now it WILL happen when damage is bad enough.
- experiment: Now if you speak in depressurized area (less than 10 kPa) only people
next to you can hear you. Radios still work though.Ideas for Improvement
By having both the yaml files for each release we can store additional data if we want to display it differently like @xezon mentioned. DisclaimerThe Baystation12 is under the AGPL-3.0 and I am not sure if that means we are allowed to copy/change it. However the actual python implementation is unlicensed |
Beta Was this translation helpful? Give feedback.
-
|
I do not like that sample change log. It is just a dump of brief titles with no additional information. This is ok for simple changes that are not user facing, but we will not be able to properly document a more complex change with this. For a simple view of changes like the one above we already have a view, albei not transferable: The git commit history: https://github.com/TheSuperHackers/GeneralsGameCode/commits/main/ My prediction is that these minimal changelogs are great to just have something in place with no big use case, but it will come back haunting us when the players will ask: "sorry what are all these things here that were changed, why is there no detailed information for it?". |
Beta Was this translation helpful? Give feedback.
-
|
Perhaps it makes sense to first align on what a change log means. Here is my take on it. What is a change log?A change log is a list of information that describe user facing changes. A change log is NOT a git commit history. A git commit (or Pull Request) can be associated with no change log entry. Multiple git commits (or Pull Requests) can be associated with 1 change log entry. Why is a change log not a git commit history? Because we already have a git commit history inside git and our customer does not care about changes that are just specific to building a product. The git commit history is for developers and we do not need a copy of it. Irrelevant things for change logs
Relevant things for change logs
Change log entry mutabilityA change log entry is mutable(!) before a major public release. A change log entry is immutable(!) after a major public release, unless the mutation is applied to correct a mistake or migrate some data. Why? Because multiple changes can mutate a change log entry before a release. But after the release, all prior change log entries are locked in and must not be touched again. Change log entry formatA change log entry (e.g. in yaml format) just contains the raw data of a change. It does NOT present the final change log that the user will see. Instead, the change log entries are used to build views from, for example as markdown, as html, or plain text. Change log entry contentA change log entry must contain rich information:
Concise titleThe title builds a very small text record for the change. This is good for most common users to look at. Detailed descriptionThe detailed description builds a longer text record to help explain the nuances and impacts of a particular change. This is good for interested users who really want to understand what is going on. Links to pull requestsThis is another complementary resource for the change. There will be even more information in the Pull Request, including the file changes that faciliated the change. It also allows to retroactively add a comment to a pull request. Tags / labelsTags and labels are absolutely essential to build different views of the change log. You only want to see entries for a specific version or version range? Add a version label. Only want to see bug fixes? Add a bug label. Only want to see GLA changes? Add a GLA label. AuthorsServes as crediting the authors of the change but also helps finding the person that has the knowledge of any particular change. |
Beta Was this translation helpful? Give feedback.
-
|
Based on this and the discussion in different forums. I agree that having as much data about a change as possible is the correct way forward. It is always easier to remove data than to get it back. This can narrow down the current path to:
This leaves us with the following issues:
|
Beta Was this translation helpful? Give feedback.
-
I hope we can just settle on the same format that we already have established in the patch and not reinvent the wheel :) It has worked fine so far for 1000 changes. Then we would need no format migration between the projects. When a release is finalized, yaml files could be merged to a master yaml for that particular release. I think yaml format allows files separated by 3 dashes. ---
content1: yaml1
---
content2: yaml2
---
content3: yaml3
It does not matter right now. What views we generate can always be changed at any time. We just need to settle on a source format.
The change log entries live in this repository. The generated change log views can live anywhere. |
Beta Was this translation helpful? Give feedback.
-
Meeting Notes 2025-03-19@xezon and I had a discussion this evening. 1. What informationWe agreed that having more information and sorting cherry pick what we want is better than wanting something we don't have. Based on a few discussion points. We came to the following points for now (subject to change, or additional)
This was thought of as the minimum amount of information that should be kept in the change file. From this information we can create views for any target of audience. If we want to have a changelog for the players, we can exclude all changes that had something to do with the build system or repository maintenance. Or if we want to also have one for the developers, we can add more information. 1.1 Additional informationWe also discussed that sometimes a PR can have been merged, only to find out later that the bug the PR intended to fix, created a new bug or didn't fix the bug entirely. For cases like this it should be possible to, update existing changelog files or use them as basis for a new file. The specifics of this is not yet ironed out. If a changelog file has been used in a release, then that file should not be changed. But maybe the new PR would like to reference or in some way link to that PR. Saving some information in the changelog file for the new PR. Lastly there is the case of wanting to add information which is relevant to the PR (videos, screenshots, tables, etc). These can feasible to store in a changelog file and will only be available through the link to the PR. 2. When should the file be generated?We spoke a bit about when the file should be created. There a different times it could be made.
3. How do we extract this information?All of this is nice and all, but we need a quick and hassle-free way to extract all this relevant information. Ideally this changelog file process should be automated with GitHub actions. This already gives is some information through the GitHub API, like the author. creation date and PR number. However descriptions of what the change entails and potential relevance to other PRs is not possible without agreeing on a format to write the PR. 3.1 Current suggestionWhat I suggested to Xezon was to have a PR template, this template is loaded as soon as the PR is started. The author then need to fill out the relevant information, so that we are able to parse the PR body for the information we want to store in changelog files. This way we ensure that if people follow out CONTRIBUTION file, we can extract all the wanted information. 3.2 Enforcing formatIf we want to automate the extraction, we will also need actions which lints the PR once it has been created. This first step ensures that the PR adheres to the agreed upon formatting. So that when we decide on when to create the changelog file we can ensure that the information needed for the changelog script is available. 4. Manual changelog file creationManual creation will be required as all the changes currently made to the repository has to be added to the list of files somehow. And automating this process is impossible as the current PRs don't have any sort of specific format. Xezon also mentioned that a feature to opt out of automatic changelog file generation could be an idea. This can be an implementation, however it also exposes us to potential lost information, if the author then don't create the changelog file manually. Additionally this will add another task to the PR reviewer as they need to ensure that the file has been made, and made correctly. They can then also not use the file as a way to get an overview of the PR. What to do now?Although nothing is final and is up for discussion. I will attempt to create a set off scripts which does what was talked about in section 1, 2 and 3. Then we will have a base to move on from. As it stands now, the script will expect a PR to have a certain format, and extract all relevant information from the PR into a .yaml file. How to store the files and what to do with them when we create a release, is not decided yet and any inputs is greatly appreciated. Please come with concerns, inputs etc in the comment of the post! |
Beta Was this translation helpful? Give feedback.
-
|
This is the current PR template. Example PR:Title: [GEN/ZH] Fixed MM when surrenduringChange list
No Automatic Changelog File
Author(s)Fixes Issue(s)Closes: #99999 |
Beta Was this translation helpful? Give feedback.
-
How do we want to keep a Changelog?
We need to agree on what we want in the changelog.
How should it look
This is kinda tied to the next point. However having a clear changelog will make it much easier (also for non-tech people) to quickly at a glance see what has been changed since the last release. Angular is usually used as the prime example. Their changelog is based on a set of commit guidelines which makes automatic changelog generation easy.
Changelog screenshot
Our changelog could look similar, and we could add more information to the table if we feel it adds value.
What information do we want
I believe the bare minimum needed for a changelog is:
More definitely makes it easier to dive deeper into each individual change:
How do we extract the information
There are many ways to do this, and all of them properly has pros and cons. I have experimented with the pyGitHub library (essentially just a python wrapper around the GitHub rest API) and it seems to work pretty well and has nice features. Other suggestions are welcome.
How/When do we create new releases
This can be both an easy and hard question. It is clear that if we manage to remove mismatches from the game that this release needs to come out ASAP. However small bug fixes that are not game breaking, should be bundled together as to limit the updates players have to go through. (Separate launcher could automatically handle updates, but that is way in the future)
Do we want to store additional metadata
Additional data could be author name, related issue, test results (if we manage to create unit/integration tests), and more genius things i can't think of.
Should we update existing commits to follow potentially new agreed standards
Depending on how long it takes to align on how to manage the changelog, this can become a bit of a task. If we decide to go with conventions on commits / PRs, the main branch would need to be rebased with new commit messages. We could also decide that we only follow convention going forward. Either could be an idea.
Automatic Changelog
I personally believe that creating a script (or using existing) adds great value and saves time (and potentially errors). This will require us to agree on some standard to keep commit / PR parsing trivial. Additionally by having clear conventions on how we write commits / PRs will also make the development easier to follow and maintain in the future.
Standardized Commits / PR
This is not a new thing, we could use conventional commits as a base and branch out from there, and update it based on our needs. Again the good thing about a standardized (conventional) way is that we all understand what a change does by essentially looking at the title, and if need be dive into the body of the change.
First Attempt
I've already given this a first attempt myself #443 (exposing some of my biases), Xezon asked some questions and came with some ideas, and I think the best way to proceed and create a great tool for our development journey should be to align on what we believe is necessary and provides value and (hopefully) improve the development speed.
Please come with your thoughts below!
Beta Was this translation helpful? Give feedback.
All reactions