[GitHub] [trafficcontrol] ocket8888 opened a new pull request, #7254: Documentation-based changelog generation

[GitBox <gi...@apache.org>]

ocket8888 opened a new pull request, #7254:
URL: https://github.com/apache/trafficcontrol/pull/7254

   <details><summary>Justification/backstory</summary>
   
   Changes between API versions are extensive, and generally aren't enumerated in the changelog - for example, in APIv5 the format of a timestamp in a Delivery Service structure changed from the TO custom timestamp to RFC3339, but that is not listed in the changelog. Such things are usually implementation details of larger changes listed in the CHANGELOG and are usually quite extensive for any given (major) version gap, so it's not reasonable to expect people to add all of that to a regular CHANGELOG. Especially not since we (try to) always require `.. versionadded::`, `.. versionchanged::`, and `.. deprecated::` directives to the documentation for Traffic Ops endpoints whenever these changes occur.
   
   So how do you know the API differences? There are two equally tedious methods today. You can read all of the documentation for one version, then all of the documentation for the other and compare what's different. Or, you could read through all of the changes for all of the PRs that went into a release that solidified the version in question, and by examining the changes to Go code and documentation you can figure out what's different.
   
   However, because we (try to) always add the Sphinx directives above, there's a much easier way that just isn't being utilized at the moment.
   
   </details>
   
   You can get a list of the changes in a version with the `changes` Sphinx builder. The only problem is that we have a project-wide version that doesn't match our API version, so the changes get messed up. There's a simple way around that, and what this PR does is expose that through our docs' makefile. Now, if you want to see the things that were added, changed, and deprecated in API version, say 4.0, you can do:
   
   ```bash
   make VERSION=4.0 apichanges
   ```
   
   ... and it spits out an HTML document summarizing those changes into `docs/build/apichanges/`. Note that if you don't specify a version, it'll default to the project version - 7.1.0 at the time of this writing.
   
   This PR also adds the ability to override the version for the already-supported `changes` target, which summarizes changes to the entire project. This is because (in the API docs specifically, but also some other places throughout the docs) the prefix `ATCv` is prepended to the version number for those directives, to make it clear that it's the project version and not an API version. So `make changes` may not give you the whole truth; it may be necessary to also look at e.g. `make VERSION=ATCv7.1`.
   
   I intend to follow this PR up with another that syncs this disparate usage across the docs to make this functionality easier to use, along with a guidelines section on the topic.
   
   <hr/>
   
   ## Which Traffic Control components are affected by this PR?
   - Documentation
   
   ## What is the best way to verify this PR?
   1. `make VERSION=4.0 apichanges` and verify output
   
   ## PR submission checklist
   - [x] This PR doesn't need tests
   - [x] This PR has documentation
   - [x] This PR doesn't need a CHANGELOG.md entry
   - [x] This PR **DOES NOT FIX A SERIOUS SECURITY VULNERABILITY**


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@trafficcontrol.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [trafficcontrol] zrhoffman merged pull request #7254: Documentation-based changelog generation

["zrhoffman (via GitHub)" <gi...@apache.org>]

zrhoffman merged PR #7254:
URL: https://github.com/apache/trafficcontrol/pull/7254


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@trafficcontrol.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org