wording

CODE_REVIEW.md

@@ -1,6 +1,6 @@
 # Code review requiements
 
-This document describe responsibilities of code reviewers when reviewing PRs.
+This document describes responsibilities of code reviewers when reviewing PRs.
 
 Pull request process is described in [contributing guide](./CONTRIBUTING.md#submitting-pull-requests)
 
@@ -10,11 +10,12 @@ Pull request process is described in [contributing guide](./CONTRIBUTING.md#subm
 - PR title follows [commit conventions](CONTRIBUTING.md#commit-conventions)
     - If PR format is different, reviewer should change it to follow the conventions
 - PR has a description with reasoning and change overview
-    - If description is missing but clear for reviewer, reviewer may add a comment or edit description
+    - If description is missing but clear for reviewer, reviewer may request the author to add the description or edit description by themselves
 - New feature or fix has tests proving it works
     - Reviewer should request changes from contributor to add tests
-- If PR changes documented behaviour, there should be update to `/docs` or inline comments
-    - Reviewer should request changes from contributor to update docs
+- If change in the PR needs documentation
+    - Reviewer should request new docs or update to existing docs
+    - `/docs` and `/docs_new` need to be kept in sync until we deprecate `/docs`
 - If PR introduces breaking changes, fixes a bug or adds a new feature, there should be a [release note](#release-notes)
     - Reviewer may request changes from the contributor to add a release note
     - Reviewer may add a release note by themself in order to unblock the merge process
@@ -32,10 +33,10 @@ We use `kueue` bot to merge approved PRs.
 If PR is approved, all checks are passing and it has the `kueue` label, it will
 be automatically squashed and merged.
 
-For PRs from Kanister developers, the committer should add the `kueue` label after
+For PRs from Kanister developers, the author should add the `kueue` label after
 PR was approved.
 
-For PRs from community, the reviewer should add the `kueue` label.
+For PRs from community members, the reviewer should add the `kueue` label.
 
 ## Release notes
 

build/reno_report.sh

@@ -30,9 +30,9 @@ reno report --output ./CHANGELOG.rst
 ## Convert rst to markdown
 rst2md ./CHANGELOG.rst --output ./CHANGELOG.md
 
-# Generate changelof for current version only:
+# Generate changelog for current version only:
 
-## Reno `--version` flag does not support "unreleased" setting and requires specific version, event if it's dynamic
+## Reno `--version` flag does not support "unreleased" setting and requires specific version, even if it's dynamic
 ## To generate dynamic version, use `reno list`.
 ## It will be replaced by `unreleased_version_title` setting in the actual report file
 UNRELEASED_VERSION=$(reno list 2>/dev/null | grep -E "^[0-9]+\.[0-9]+\.[0-9]+\-[0-9]+")

releasenotes/README.md

@@ -1,22 +1,20 @@
 ## Release notes
 
-Release notes use [https://docs.openstack.org/reno/latest/](reno)
-
-Release notes are stored in `releasenotes/notes` directory.
+Release notes are generated using [https://docs.openstack.org/reno/latest/](reno) and are stored in `releasenotes/notes` directory.
 
 Reno allows to generate release notes using files in the repository as opposed to generating from commit messages.
 This makes it easier to review and edit release notes.
 
 ## Development flow
 
 When submitting a PR with some changes worthy of mentioning in the notes (new feature, bugfix, deprecation, update requirements),
-committer should add a new note file using `reno new <note_name>` or `make reno-new note=<note_name>`.
+committer should add a new note file using `reno new <note_name> --edit` or `make reno-new note=<note_name>`.
 
 New file will be created in `releasenotes/notes` directory with default template.
 Summary of the change should be added to this file to reflect the change and additional information such as deprecations or upgrade requirements.
 It's recommended to remove unused template fields.
 
-When reviewing a PR, a reviewer should check if there are change notes added if necessary and either request or add a new note if they have push access to the branch
+When reviewing a PR, a reviewer should check if there are release notes added if necessary and either request or add a new note if they have push access to the branch.
 
 ## Generating changelogs
 
@@ -33,9 +31,9 @@ make reno-report VERSION=$CURRENT_VERSION
 ```
 
 This will create a CHANGELOG.md and CHANGELOG_CURRENT.md files with changes from committed release notes.
-CHANGELOG_CURRENT.md only containing changes for the current version.
+CHANGELOG_CURRENT.md will only contain changes for the current version.
 
-It will be used when running goreleaser build using make (will use `CHANGELOG_CURRENT.md` by default):
+Changelog file can be specified when running goreleaser build using make (will use `CHANGELOG_CURRENT.md` if not specified):
 
 ```
 make gorelease CHANGELOG_FILE=./CHANGELOG_CURRENT.md