# 20200808 Notes for release notes design

> Does the following design sound feasible:
>
>* Include a changelog.yml file inside each of the build directory (or changelog.d/ that contains the yaml files)

What do you mean by "build directory" here? Are you referring to having a file or directory in each branch of the fcos configs repo?

>
>* merge the yaml files from last release build upto the next release builds into a single release changelog file, and also de-dup the changelog

Yep. I'm thinking that when we take the contents from the `/.d` directory on the `testing-devel` stream and merge it together and put it under a `nextrelease` entry in the yaml.

Once we do the release we update the entry in the yaml to be the version number from the build we just put out.

Example toplevel yaml:

releases:
  - nextrelease:
    - removed package xyz
        - This package was causing problems. Workaround by foo foo foo.
    - added package abc
    - fixed [bug3](https://example.com/bug3)
  - 32.20200629.3.0:
    - removed package xyz
    - added package abc
    - fixed [bug4](https://example.com/bug3)

`nextrelease` would then get replaced when we put out the release. There are a lot of mechanics here and a lot of ways to do this. I think the important part is that we get something in place and then start ot iterate on it.

>
>* release page use the final changelog yaml file to display desired information

👍

Another thing to think about is the format of the yaml file. Would we accept markdown and then try to render it as html?

# Please add the desired release notes to the `next-release` section as list items.
#
# Each list item should be a dictionary with structure:
# - subject: removed package xyz
#   body: xyz introduced bug which is related to (https://example.com/bug3).
#
# For example:
# ---
# next-release:
#   - subject: removed package xyz
#     body: This package was causing problems. Workaround by foo foo foo.
#   - subject: added package abc
#   - subject: fixed [bug3](https://example.com/bug3)

next-release:
  # item 1
  - subject: ""
    body: ""
  # item 2
  - subject: ""
    body: ""

mv releasenotes.yaml 2020-releasenotes.yaml 2019 2018

1. Dusty opens PR to testing-devel repo to fedora-coreos-config repo
- adds release note to release-notes.d/fixed-ignition-bug.yaml
- fixed bug [77](https://link/to/bug/77) in ignition all nodes now use DHCP
- PR gets merged
2. Allen opens PR to testing-devel repo to fedora-coreos-config repo
- adds release note to release-notes.d/fixed-afterburn-bug.yaml
- fixed bug 87[https://link/to/bug/87] in afterburn all nodes now use ecdsa SSH keys
- PR gets merged
3. We want to do a `testing` release
- merge `testing-devel` into `testing`
- run a build through the build pipeline
- this is the step where we learn what the version number is (i.e. 32.20200629.3.0)
- we do some final checks (mostly just little inspections)
- then we run the release pipeline
- replicates to aws regions
- copies ostree content to prod repo
- Then we run fedora-coreos-stream-generator
- metadata processing
- Copy metadata to S3
- Update server (cincinatti) picks up new metadata from s3, serves updates
- Website picks up new metadata from s3, serves updates

Proposal:

Have a tool that runs independently of the pipeline like bump-lockfile and sync-stream-metadata jenkins jobs. This tool will trigger based on a new release of FCOS or can be triggered manually:

##### Git repository manipulation
- look at the release-notes.yaml file for the related branch (i.e. `testing`)
- if an entry for that release exists, it does nothing to the git repo
- if an entry for that release does not exist
- create a new entry in release-notes.yaml for that release
- merge the release-notes.d/* files into release-notes.yaml
- delete release-notes.d/* files from that branch
- delete corresponding release-notes.d/* files from `testing-devel` branch
#### intermediate processing to get into ideal form for website code consumption
- process release-notes.yaml (maybe convert to JSON or something)
#### Upload to place where website can consume
- upload to s3

- merge the release-notes.d/* files in the related branch (i.e. `testing`) into the release-notes.yaml file
- It will create a new entry for that release
- some tool merges files in release-notes.d/* into release-notes.yaml
- ```
releases:
- 32.20200629.3.0:
- inline: |
- fixed bug [77](https://link/to/bug/77) in ignition all nodes now use DHCP
- fixed bug [87](https://link/to/bug/87) in afterburn all nodes now use ecdsa SSH keys
- 32.20200619.3.0:
- DISCLAIMER: There was a serious flaw affecting this release that causes AWS nodes to reboot after 4 hours of uptime.
- old release note 1
- old release note 2

        - push commit to testing-devel branch to delete existing `release-notes.d/*` files