doc: Update dev docs for development and releases

.github/pull_request_template.md

@@ -22,8 +22,6 @@ If this change should be part of the Release Notes,
 **replace this entire paragraph** with 1-3 sentences about the changes.
 Otherwise, you **MUST** remove this section entirely.
 
-## Breaking Changes
-
 Does this PR contain any breaking changes?
-If so **replace this entire paragraph** with a description of these changes.
-Otherwise, you **MUST** remove this section entirely.
+If so, add `## Breaking Changes` header and list the introduced changes there.
+

.github/release-drafter.yml

@@ -55,9 +55,6 @@ autolabeler:
   - label: breaking-change
     body:
       - '/^## Breaking Changes/im'
-  - label: release-notes
-    body:
-      - '/^## Release Notes/im'
   # Version labels.
   - label: minor
     title:

.github/scripts/release-notes.sh

@@ -23,9 +23,10 @@ extract_header() {
 	local header_name="$2"
 	awk "
     /^\s?$/ {next}
-    /## $header_name/ {rn=1}
-    rn && !/^##/ {print};
-    /##/ && !/## $header_name/ {rn=0}" <<<"$commit"
+    /^## $header_name/ {rn=1}
+    rn && !/^##/ && !/^--+/ {print};
+    /^--+/ {rn=0};
+    /^##/ && !/^## $header_name/ {rn=0}" <<<"$commit"
 }
 
 indent() {
@@ -45,10 +46,7 @@ while IFS= read -r line; do
 		fi
 		rls_header="${BASH_REMATCH[1]}"
 	fi
-	if [[ $rls_header == "" ]]; then
-		continue
-	fi
-	if [[ $line != -* ]]; then
+	if [[ $rls_header == "" ]] || [[ $line != -* ]] || [[ $line == *"@renovate"* ]]; then
 		continue
 	fi
 	if ! [[ $line =~ $commit_message_re ]]; then

.markdownlint.yaml

@@ -0,0 +1,10 @@
+MD010:
+  code_blocks: false
+  spaces_per_tab: 1
+MD013:
+  line_length: 80
+  heading_line_length: 80
+  code_block_line_length: 120
+  code_blocks: true
+MD024:
+  siblings_only: true

Makefile

@@ -134,7 +134,7 @@ check/trailing:
 check/markdown:
 	$(call _print_step,Verifying Markdown files)
 	$(call _ensure_installed,yarn,markdownlint)
-	yarn --silent markdownlint '*.md' --disable MD010 # MD010 does not handle code blocks well.
+	yarn --silent markdownlint '**/*.md' --ignore node_modules
 
 ## Check for potential vulnerabilities across all Go dependencies.
 check/vulns:

DEVELOPMENT.md → docs/DEVELOPMENT.md

@@ -1,6 +1,14 @@
 # Development
 
 This document describes the intricacies of sloctl development workflow.
+If you see anything missing, feel free to contribute :)
+
+## Pull requests
+
+[Pull request template](.github/pull_request_template.md)
+is provided when you create new PR.
+Section worth noting and getting familiar with is located under
+`## Release Notes` header.
 
 ## Makefile
 
@@ -13,6 +21,12 @@ versions declaration located in Makefile.
 If you see any discrepancies between CI and your local runs, remove the
 binaries from `bin` and let Makefile reinstall them with the latest version.
 
+## CI
+
+Continuous integration pipelines utilize the same Makefile commands which
+you run locally. This ensures consistent behavior of the executed checks
+and makes local debugging easier.
+
 ## Testing
 
 In addition to standard unit tests, sloctl is tested with
@@ -48,22 +62,7 @@ how they're executed.
 
 ## Releases
 
-We're using [Release Drafter](https://github.com/release-drafter/release-drafter)
-to automate release notes creation. Drafter also does its best to propose
-the next release version based on commit messages from `main` branch.
-
-Release Drafter is also responsible for auto-labeling of pull requests.
-It checks both title and body of pull request and adds appropriate labels. \
-**NOTE:** The auto-labeling mechanism will not remove labels once they're
-created. For example, If you end up changing PR title from `sec:` to `fix:`
-you'll have to manually remove `security` label.
-
-On each commit to `main` branch, Release Drafter will update the next release
-draft. Once you're ready to create new version, simply publish the draft.
-
-In addition to Release Drafter, we're also running a script which extracts
-explicitly listed release notes and breaking changes which are optionally
-defined in `## Release Notes` and `## Breaking Changes` headers.
+Refer to [RELEASE.md](./RELEASE.md) for more information on release process.
 
 ## Dependencies
 

docs/RELEASE.md

@@ -0,0 +1,25 @@
+# Release process
+
+The internal release process is described in great detail
+[here](http://go/sloctl-release).
+
+## Release automation details
+
+We're using [Release Drafter](https://github.com/release-drafter/release-drafter)
+to automate release notes creation. Drafter also does its best to propose
+the next release version based on commit messages from `main` branch.
+
+Release Drafter is also responsible for auto-labeling pull requests.
+It checks both title and body of the pull request and adds appropriate labels. \
+**NOTE:** The auto-labeling mechanism will not remove labels once they're
+created. For example, If you end up changing PR title from `sec:` to `fix:`
+you'll have to manually remove `security` label.
+
+On each commit to `main` branch, Release Drafter will update the next release
+draft. Once you're ready to create new version, simply publish this draft.
+
+In addition to Release Drafter, we're also running a script which extracts
+explicitly listed release notes and breaking changes which are optionally
+defined in `## Release Notes` and `## Breaking Changes` headers.
+It also performs a cleanup of the PR draft mitigating Release Drafter
+shortcomings.