docs: rebuild KB in OKF v0.1 with live-verified facts
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.
This commit is contained in:
Frank
@@ -0,0 +1,115 @@
|
||||
---
|
||||
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)
|
||||
Reference in New Issue
Block a user