chore: make release doc more readable (#115)

Signed-off-by: a3hadi <[email protected]>

development.md

@@ -40,16 +40,16 @@ Note: before running the script, ensure that through the CLI, you are logged int
 After confirming that your changes pass local testing:
 
 1. Clean up testing artifacts
-2. Create a PR. Once your PR has been merged, a Github Actions workflow (Docker Publish) will be triggered, to build, tag (with `stable`), and push
+2. Create a PR. Once your PR has been merged, a Github Actions workflow (`Docker Publish`) will be triggered, to build, tag (with `stable`), and push
 all example images. This ensures that all example images are using the most up-to-date version of the SDK, i.e. the one including your 
 changes
 
 ### Adding a New Example
 
-If you add a new example, there are a few steps to follow in order for it to be used by the update script and the Docker
-Publish workflow:
+If you add a new example, there are a few steps to follow in order for it to be used by the update script and the 
+`Docker Publish` workflow:
 
-1. Add the example to the `pom.xml` file in the examples directory, within an execution element. Note that the
+1. Add the example to the `examples/pom.xml`, within an execution element. Note that the
 `id` tag you specify must be exactly the same as the quay.io repository name for the example
 2. Add the `id` tag you specified in step 1 to the `executionIDs` array in `hack/update_examples.sh`
 3. Add the `id` tag you specified in step 1 to the `execution_ids` matrix in `.github/workflows/build-push.yaml`

releases.md

@@ -4,23 +4,28 @@ This document explains the release process for the Java SDK. You can find the mo
 
 ### Before Release
 
-Before releasing a new SDK version, make sure to update all references from the old version to the new one.
+1. Before releasing a new SDK version, make sure to update all references from the old version to the new one.
 For example, the version in the `README.md`, as well as the `pom.xml` in the root and example directories should be updated (for [reference
-](https://github.com/numaproj/numaflow-java/pull/89/files#diff-9c5fb3d1b7e3b0f54bc5c4182965c4fe1f9023d449017cece3005d3f90e8e4d8)). The specified version should follow the [semantic versioning](https://semver.org/) specification. After making these changes, create a PR. Once merged, it will trigger the `Docker Publish` workflow, and should be included in the release.
+](https://github.com/numaproj/numaflow-java/pull/89/files#diff-9c5fb3d1b7e3b0f54bc5c4182965c4fe1f9023d449017cece3005d3f90e8e4d8)). The specified version should follow the [semantic versioning](https://semver.org/) specification
+2. If version to be released has backwards incompatible changes, i.e. it does not support older versions of the Numaflow platform,
+you must update the `MINIMUM_NUMAFLOW_VERSION` constant in the `src/main/java/io/numaproj/numaflow/info/ServerInfo.java` file to the minimum Numaflow version 
+that is supported by your new SDK version
+3. After making these changes, create a PR. Once merged, it will trigger the `Docker Publish` workflow, and should be included in the release.
 As a result, the correct SDK version will always be printed in the server information logs, and the example images will
-always be using the latest changes (due to pointing to the local maven repository that is built).
-
-If version to be released has backwards incompatible changes, i.e. it does not support older versions of the Numaflow platform,
-you must update the `MINIMUM_NUMAFLOW_VERSION` constant in the `src/main/java/io/numaproj/numaflow/info/ServerInfo.java` file to the minimum Numaflow version that is supported by your new SDK version.
-Ensure that this change is merged and included in the release.
+always be using the latest changes (due to pointing to the local maven repository that is built)
 
 ### How to Release
 
-This can be done via the Github UI. In the `Releases` section of the Java SDK repo, click `Draft a new release`. Create a tag that has the same name as the version that you specified in the root
-`pom.xml` prefixed with a `'v'`, and select it. Make the title the same as the tag. Click `Generate release notes` so that all the changes made since the last release are documented. If there are any major features or breaking
-changes that you would like to highlight as part of the release, add those to the description as well. Then set the release as either pre-release or latest, depending
-on your situation. Finally, click `Publish release`, and your version tag will be the newest release on the repository.
+This can be done via the Github UI. 
+1. In the `Releases` section of the Java SDK repo, click `Draft a new release`
+2. Create a tag that has the same name as the version that you specified in the root
+`pom.xml`, prefix it with a `'v'`, and select it
+3. Make the title the same as the tag
+4. Click `Generate release notes` so that all the changes made since the last release are documented. If there are any major features or breaking
+changes that you would like to highlight as part of the release, add those to the description as well
+5. Select `Set as the latest release` or `Set as a pre-release`, depending on your situation
+6. Finally, click `Publish release`, and your version tag will be the newest release on the repository
 
 ### After Release
 
-After your release a Github Actions workflow, `Publish to Maven Central and Github Packages`, will be triggered. Monitor the workflow run and ensure that it succeeds.
+After your release, a Github Actions workflow, `Publish to Maven Central and Github Packages`, will be triggered. Monitor the workflow run and ensure that it succeeds.