Frank
02883d3ed2
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
116 lines
4.1 KiB
Markdown
116 lines
4.1 KiB
Markdown
---
|
|
type: reference
|
|
title: SDLC and Tooling Best Practices
|
|
description: Current best practices for the software development life cycle - git, CI/CD, testing, review, versioning, and dev environments.
|
|
tags:
|
|
- sdlc
|
|
- git
|
|
- ci-cd
|
|
- testing
|
|
- tooling
|
|
- unverified
|
|
timestamp: 2026-08-11
|
|
---
|
|
verified: 2026-08-28
|
|
|
|
# SDLC and Tooling Best Practices
|
|
|
|
This page distills current (2025/2026) best practices for running a software project. Use it when you bootstrap a new repository or when you review an existing one.
|
|
|
|
## Git Branching
|
|
|
|
Trunk-based development dominates. Teams use short-lived feature branches and merge into a single shared `main` branch. Feature flags hide incomplete features. This replaces older models such as GitFlow for most projects.
|
|
|
|
Use GitHub Flow as the default for new projects. Create a branch for each change. Open a pull request for every change. Merge the change after review. Deploy from `main` at any time.
|
|
|
|
The rule `main` must stay deployable at all times.
|
|
|
|
## Continuous Integration and Delivery
|
|
|
|
GitHub Actions is the most common CI/CD platform. Workflows live in `.github/workflows/`. A standard workflow follows this order: lint, test, build, deploy.
|
|
|
|
Use these patterns:
|
|
|
|
* Run one pipeline for pull request checks.
|
|
* Run a separate pipeline for `main` branch deployments.
|
|
* Use matrix builds to test multiple tool versions.
|
|
* Cache dependencies between runs.
|
|
* Split shared steps into reusable workflows.
|
|
|
|
## Testing
|
|
|
|
Follow the testing pyramid. Write many unit tests. Write fewer integration tests. Write the fewest end-to-end tests.
|
|
|
|
| Layer | Speed | Focus |
|
|
|-------|-------|-------|
|
|
| Unit | Fast | Isolated functions and modules |
|
|
| Integration | Medium | Service-to-service interaction |
|
|
| End-to-end | Slow | Complete user journeys |
|
|
|
|
Aim for roughly ten unit tests per integration test, and ten integration tests per end-to-end test.
|
|
|
|
## Code Review
|
|
|
|
Reduce review friction with these tools:
|
|
|
|
* Pull request templates for consistency.
|
|
* `CODEOWNERS` to assign reviewers by path.
|
|
* Required review before merge.
|
|
* Pre-commit hooks for lint and format checks.
|
|
|
|
## Semantic Versioning
|
|
|
|
Version numbers follow the `MAJOR.MINOR.PATCH` format.
|
|
|
|
* MAJOR changes when an API breaks compatibility.
|
|
* MINOR changes when features stay compatible.
|
|
* PATCH changes fix bugs in a compatible way.
|
|
|
|
Pre-release versions use `-alpha`, `-beta`, or `-rc` suffixes.
|
|
|
|
## Development Environments
|
|
|
|
Use `mise` to manage tool versions, environment variables, and named tasks in one `mise.toml` file. `mise` replaces the separate tools asdf and direnv, and it replaces a `Makefile` for tasks.
|
|
|
|
Use Dev Containers for reproducible environments. The Dev Container Specification uses `.devcontainer/devcontainer.json`. It works with VS Code, Codespaces, and the container CLI.
|
|
|
|
## Per-Ecosystem Variations
|
|
|
|
| Ecosystem | Manifest | Package manager | Test command |
|
|
|-----------|----------|-----------------|--------------|
|
|
| Node/JS | `package.json` | npm, pnpm, or Bun | `vitest` / `jest` |
|
|
| Python | `pyproject.toml` | uv | `pytest` |
|
|
| Rust | `Cargo.toml` | cargo | `cargo test` |
|
|
| Go | `go.mod` | go modules | `go test ./...` |
|
|
| Terraform | `.tf` files | providers | `terraform validate` |
|
|
|
|
Put `AGENTS.md` instructions for each ecosystem in the [Agent Instruction Files](agents-files.md) page.
|
|
|
|
## Monorepos
|
|
|
|
Use a workspace tool for monorepos:
|
|
|
|
* Turborepo or Nx for JavaScript/TypeScript.
|
|
* pnpm workspaces for dependency management.
|
|
* Cargo workspaces for Rust.
|
|
* Go workspaces for Go modules.
|
|
* uv workspaces for Python.
|
|
|
|
Put a nested `AGENTS.md` in each package when a monorepo has multiple packages.
|
|
|
|
## Citations
|
|
|
|
* [Trunk-Based Development](https://trunk-based-development.com/)
|
|
* [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow)
|
|
* [GitHub Actions](https://docs.github.com/en/actions)
|
|
* [Microsoft Engineering Playbook](https://microsoft.github.io/code-with-engineering-playbook/)
|
|
* [semver.org](https://semver.org/)
|
|
* [mise](https://mise.jdx.dev/)
|
|
* [Dev Container Specification](https://containers.dev/)
|
|
|
|
## See Also
|
|
|
|
* [Agent Instruction Files](agents-files.md)
|
|
* [Language and Framework Stacks](languages/index.md)
|
|
* [Infrastructure and Cloud](infra/index.md)
|