docs: improve documentation regarding ECR dev-release

Author: laxa1986

docs/artifact-types/aws-ecr.md

@@ -131,17 +131,16 @@ It also uses OIDC to assume an IAM role and access CodeArtifact in read-only mod
 
 ## dev-release
 
-ECR supports [dev-release](../features/dev-release.md): Docker image gets published with tag equal to branch name
-(branch name `feature/login` becomes ECR tag `feature-login`).
-`agilecustoms/release` action enforces branch name prefix (configured via `dev-branch-prefix`, default is `feature/`).
-On the other hand, the ECR supports lifecycle rules by tag prefix.
-So if you apply both — you can be sure that all self-service artifacts are removed automatically in a few days!
-
-There is one important gotcha: you can't re-run dev-release for immutable ECR repo:
-- immutable ECR repo prevents pushing image for an existing tag
-- tag can be deleted, but IAM doesn't allow to configure permissions selectively for tag prefix,
-  so if you allow deleting tags — it is a risk that a developer can remove some non-dev tag
-- if you make ECR repo mutable — it is a risk that a developer can override a non-dev tag
-
-So if you need to re-run dev-release shortly (before old tag expired), the workaround is just to create a new branch:
-`feature/login` -> `feature/login-2` and run dev-release from it
+`agilecustoms/release` supports ECR [dev-release](../features/dev-release.md):
+Docker image gets published with tag equal to branch name (branch name `feature/login` becomes ECR tag `feature-login`).
+
+ECR has two great features:
+- immutable repo with exclusions
+- support lifecycle rules by tag prefix
+
+`agilecustoms/release` action enforces branch name prefix (configured via `dev-branch-prefix`, default is `feature/`)
+
+Combine all together:
+- you can allow your dev team to make dev-releases from `feature/` branches
+- developers can re-run dev-release workflow on the same branch if needed, because ECR repo is immutable with exclusion for `feature-*` tags
+- corresponding images will be automatically removed thanks to lifecycle rules by tag prefix, so you don't worry about overspending on ECR storage

docs/features/dev-release.md

@@ -34,7 +34,7 @@ The table below shows a comparison of different release types:
 Dev release allows publishing artifacts temporarily for testing purposes:
 you push your changes to the feature branch, the branch name becomes this dev-release version:
 - SemVer is _not_ generated
-- no automated pushes, so no need for PAT
+- no automated git pushes, so no need for PAT
 - no git tags created, files in branch addressable by branch name
 - `/` gets replaced with `-`, so branch `feature/login` gives version `feature-login`
 - parameter `dev-branch-prefix` (default value is `feature/`) enforces branch naming for dev releases.
@@ -113,14 +113,18 @@ Artifact types that support dev-release:
 
 ## Security
 
+_Note: here we assume you use a centralized AWS account for storing artifacts: files in S3, images in ECR
+and (less popular) software packages in CodeArtifact. Lets call such account a Distribution or "Dist" account.
+You create and store an artifact once (in the Dist account) and then deploy/use in any workload (dev, test, prod) account_
+
 Dev-release mode brings self-service capabilities but also brings security risks
 
 _You can't guarantee dev-release security if anybody can assume your 'ci/publisher' role.
 Or if anybody can use powerful GH PAT to make arbitrary Git changes and then run a malicious workflow on the main branch.
 In this section we assume you already have a secure GitHub setup and AWS authorization, see [Authorization and security](../authorization.md)_
 
 Now lets focus on risks coming specifically from dev-release. Developers may try to use dev-release workflow to:
-1. _Create_ unverified artifact that looks like normal
+1. _Create_ an unverified artifact that looks like normal
 2. _Update_ (override) existing production artifact
 3. _Delete_ production artifact
 
@@ -155,7 +159,7 @@ For `ci/publisher` role you might think you need to trust only protected branche
 But in GitHub if a workflow uses an environment — it takes precedence in OIDC token,
 so on AWS side instead of "trust main branch" you would need to configure "trust release environment" type of trust policy.
 See [terraform-aws-ci-publisher](https://github.com/agilecustoms/terraform-aws-ci-publisher) for trust policy examples.
-See [GitHub Authorization](../authorization.md#github-authorization-and-security) why environment is needed in the first place
+See [GitHub Authorization](../authorization.md#github-authorization-and-security) why GH "environment" is needed in the first place
 
 ## Risk analysis
 
@@ -179,7 +183,7 @@ What can a malicious developer do?
 
 ### S3 Risks
 
-Feature branch name is used as suffix for dev-release artifacts, so `ci/publisher-dev` can only put objects at path `mycompany-dist/*/feature*`
+Feature branch name is used as suffix for dev-release artifacts, so `ci/publisher-dev` can only put objects at path `mycompany-dist/*/feature*`.
 Imagine a software product which release consists of multiple files like this:
 ```
 <bucket>/myservice/v1.2.3/