Finish up cdt-gdb-adapter #379: "Releasing" docs (#182)

* Added "Releasing" section to DEVELOPMENT.md

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

DEVELOPMENT.md

@@ -47,3 +47,60 @@ The short step-by-step version is:
 3. Add a breakpoint somewhere useful, such as [`launchRequest`](https://github.com/eclipse-cdt-cloud/cdt-gdb-adapter/blob/6ba0de8e466f4953501181f53ecdfb14c7988973/src/desktop/GDBTargetDebugSession.ts#L94)
 4. Add `"debugServer": 4711` to the launch configuration in the extension development host. The `4711` is the port number that cdt-gdb-adapter is listening on.
 5. Debug the C/C++ program in the extension development host.
+
+## 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-vscode/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-vscode` repository.
+        - Prefix issues from the sibling project `cdt-gdb-adapter` with their name if a change was
+          made in cdt-gd-vscode to resolve it.
+    - If an update of `cdt-gdb-adapter` is included, then add a section `Update to cdt-gdb-adapter vX.Y.Z`.  
+      Include the release notes as listed in [`cdt-gdb-adapter` CHANGELOG](https://github.com/eclipse-cdt-cloud/cdt-gdb-adapter/blob/main/CHANGELOG.md).  
+      Make sure to prefix issue and PR links correctly if they point to the`cdt-gdb-adapter`repository.
+- 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-vscode/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.
+    - If an update of `cdt-gdb-adapter` is included, then add a section `Update to cdt-gdb-adapter vX.Y.Z`.  
+      Include the release notes as listed in [`cdt-gdb-adapter` CHANGELOG](https://github.com/eclipse-cdt-cloud/cdt-gdb-adapter/blob/main/CHANGELOG.md).  
+      Make sure to prefix issue and PR links correctly if they point to the `cdt-gdb-adapter` repository.
+- 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, uploads release artifacts to GitHub,
+  and finally pushes releases to the [Open VSX Registry](https://open-vsx.org/extension/eclipse-cdt/cdt-gdb-vscode)
+  and the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=eclipse-cdt.cdt-gdb-vscode).
+  It may take a few minutes for this and the release's asset list to complete, and for the extensions to show up
+  on the other registries.
+
+**Note**:
+
+- If CI should fail before the GitHub asset upload, you can try to rerun the failing GitHub action.
+- Should one of the registry pushes fail while the other succeeds, you can try to rerun the failing 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/).