Finish up #379: "Releasing" docs (#453)

* "Releasing" docs

Signed-off-by: Jens Reinecke <[email protected]>

* Feedback jonahgraham

Signed-off-by: Jens Reinecke <[email protected]>

---------

Signed-off-by: Jens Reinecke <[email protected]>

Author: jreineckearm

README.md

@@ -99,3 +99,56 @@ However, if you are writing tests and developing this module independently you c
 configurations in the launch.json with VS Code. For example, if you open a \*.spec.ts file in VS Code
 you can use the "Mocha Current File & launch Server" configuration to automatically launch the debug
 server in one debugged process and the test in another.
+
+## Releasing
+
+### Prepare a release with a Pull Request
+
+- Check if security scans require dependency updates in [package.json](./package.json).
+  See [here](https://github.com/eclipse-cdt-cloud/cdt-gdb-adapter/security/code-scanning).
+- Update [CHANGELOG.md](./CHANGELOG.md).
+    - Make sure it contains a section with the new version at the top of the file.  
+      If individual commits after the last release already added a new section,
+      then rename this section accordingly.
+    - Review the commit history since the last release and add any user facing changes which
+      haven't been added yet.
+        - Add references to issues/PRs where possible. Use the format of previous releases.  
+          Putting the displayed issue number in backticks is important to avoid that a web
+          frontend automatically adds links. For example if referencing an issue/PR outside
+          this repository which has the same number like an issue in the`cdt-gdb-adapter`repository.
+        - Prefix issues from the sibling project `cdt-gdb-vscode` with their name if a change was
+          made in cdt-gd-adapter to resolve it.
+    - Look out for (internal) API changes that may impact downstream variants as part of the commit history
+      review. Such downstream variants may for example derive from classes like `GDBDebugSessionBase`.
+      Expectation is though that such changes are identified and added already during individual PR reviews.  
+      Sometimes, it can be difficult to spot such changes that can come with refactoring.
+      Consider to retrospectively update sections of previously released versions with API
+      changes to warn late adopters.
+- Update the `version` entry in [package.json](./package.json) to the new version.  
+  If the release only introduces defect fixes without significant feature changes,
+  then bump the third ("patch") version digit.  
+  Bump the second ("minor") version digit when new features have been added.  
+  Update the first ("major") version digit if there are changes that remove features
+  or significantly change existing behavior.
+
+### Start the publishing
+
+After the PR has been reviewed and merged, go to the GitHub [releases page](https://github.com/eclipse-cdt-cloud/cdt-gdb-adapter/releases):
+
+- Click `Draft a new release`.
+- Click the `Select Tag` dropdown and enter the new version in the form `vX.Y.Z`.
+- Click the `Generate release notes` button. This inserts a release name based on the
+  selected tag. And creates a list of commits since the last release as release notes
+  that are shown on GitHub.
+- Select whether the release is a pre-release and/or if it is the latest release to show
+  on the GitHub repository page. Usually, no change of the defaults is required.
+- Click the `Publish release` button. This creates a new release and pushes the defined tag.
+  The tag push triggers a GitHub action which builds, tests and finally uploads release
+  artifacts. It may take a few minutes for this and the release's asset list to complete.
+
+**Note**:
+
+- If CI should fail before the GitHub asset upload, you can try to rerun the failing GitHub action/jobs.
+- If more fixing is needed, you unfortunately may need to again bump the version number and repeat the entire process.
+
+**Important**: Making a CDT GDB Debug Adapter release requires you to be a [committer](https://www.eclipse.org/membership/become-a-member/committer/).