Learn Semantic Release - Organization Standards & Training

#Introduction

In episode 19 we connected release with deployment through GitOps. But there's one fuel that decides everything: commit message quality. semantic-release is only as good as the commits coming in — if a team member writes fix: fix bug, the analyzer can't guess any change type and no release ships. The best configuration in the world won't help if the standard isn't documented and taught.

In this episode we cover:

1. Documenting commit message, branching, and release process standards.
2. Onboarding new developers toward Conventional Commits.
3. Code review checklists for PRs and releases.

#Main Discussion

#Standards Start with Documentation

Rules that only live in a senior engineer's head are rules that are never followed. Organization standards must be:

• Written in the repository, not in chat or in slides that get lost.
• Versioned together with the code, so they get reviewed and updated too.
• Easy to find — one canonical place, then linked from everywhere.

The two most impactful documents: CONTRIBUTING.md for contributors, and docs/release-process.md for anyone involved in releases.

#CONTRIBUTING.md: The Commit Guidelines Section

Start CONTRIBUTING.md with a firm commit guidelines section. A minimal template:

## Conventional Commits
 
Every commit must follow the Conventional Commits specification:
 
Format: `type(scope): subject`
 
Types used:
 
- `feat` - new feature, triggers a minor release
- `fix` - bug fix, triggers a patch release
- `perf`, `refactor`, `docs`, `test`, `style`, `chore`, `build`, `ci`, `revert`
 
Special rules:
 
- Breaking change: write a `BREAKING CHANGE:` footer or add an exclamation mark
  to the subject, e.g.: `feat!: drop Node 16 support`
- Scope optional, must be a short noun: `feat(auth): add SSO`
- Subject imperative, lowercase, no trailing period
- Body explains why, not what
 
Read the full specification at conventionalcommits.org before your first commit.

A standard written like this can be translated directly into commitlint rules — so documentation and enforcement read from the same source and never drift apart.

#Documenting the Branching Model

The second part of CONTRIBUTING.md is the branching model. A team that doesn't understand where to push will create its own chaos:

Strict rules that must be documented:

• All changes go through Pull Requests; no direct pushes.
• main and staging are protected by branch protection.
• Merging staging to main is the only path to production.
• feature/* branches are deleted after merge.

#Developer Onboarding: From Zero to a Correct Commit

Onboarding isn't just giving repository access. A flow that works in the real world:

1. The developer reads CONTRIBUTING.md — make it part of the first task.
2. The developer runs the dependency install, then husky automatically installs the hooks.
3. commitlint checks every commit message; non-conventional commits are rejected before they ever reach git history.

The commitlint plus husky setup already discussed in episodes 3 and 9 remains the backbone:

npm install --save-dev @commitlint/cli @commitlint/config-conventional
npx husky init
npx husky add .husky/commit-msg "npx --no -- commitlint --edit $1"
git commit -m "feat: add SSO login"

With this hook, developers learn from the machine, not from a reviewer's scolding. Mistakes are caught as early as possible — that's the fastest feedback loop for building habits.

#Code Review Checklists for PRs and Releases

Review isn't just checking code — it's also a quality gate for releases. A practical checklist:

• Commit messages follow Conventional Commits and their scopes are correct.
• Breaking changes are clearly documented, both in the commit and the PR description.
• PRs that change the application's public behavior are labeled and their impact stated.
• The dry-run result makes sense: feat produces minor, fix produces patch.
• The generated changelog is readable: every entry explains a real change, not a copy-paste of commit titles.
• No tokens, passwords, or credentials leak in the diff.

For releases, add post-release checks:

• The version tag ships as expected — not minor when it should be major.
• The GitHub Release contains the correct changelog.
• That version's image was built successfully and deployed to the right environment.

The most effective release review happens when the PR is merged, not once the release is out — that's where the version decision is truly made.

#Documenting the Release Process

Finally, write docs/release-process.md so there's no mystery:

• When a release happens: automatically on merge to staging and main.
• Who is responsible if a release fails midway.
• What must be checked before a production release.
• Rollback steps: git revert v1.3.0 then release again, or redeploy the previous version.

#Conclusion

In this episode we built the human foundation on top of the machine foundation:

• Written standards in CONTRIBUTING.md and docs/release-process.md.
• The branching model documented: main stable, staging rc, feature/* temporary.
• Onboarding uses commitlint and husky as an impatient teacher.
• Review checklists cover commits, versions, changelogs, and security.

Now a single team can work consistently. In episode 21 we'll take that consistency to a larger scale — shared config, reusable workflows, and monorepo strategy. See you there!