# Software Engineering Standards These standards are the canonical engineering policy for tbieg.info. They apply to human-written and AI-assisted changes alike. ## 1. Priorities In order of importance: 1. Correctness and safety 2. Accessibility and usability 3. Maintainability and clarity 4. Security and privacy 5. Performance 6. Visual polish Prefer the simplest implementation that satisfies the requirement without creating avoidable future complexity. ## 2. Source control - `main` represents the intended production source state. - Make changes in small, coherent commits with descriptive imperative commit messages. - Do not commit generated secrets, credentials, private keys, certificates, tokens, editor state, logs, or operating-system artifacts. - The repository is the source of truth. Production files are deployment targets, not the primary editing location. - Review the diff before committing or deploying. ## 3. Web architecture - Prefer standards-based HTML, CSS, and JavaScript over unnecessary frameworks. - Use semantic HTML and progressive enhancement. - Keep content, presentation, and behavior separated where practical. - JavaScript modules must be served with correct MIME types. Local development uses `npx serve`, not Python's simple HTTP server. - Avoid dependencies unless they provide clear value that outweighs maintenance and supply-chain cost. - Pin or lock dependencies when dependencies are introduced. ## 4. Accessibility Accessibility is a feature, not post-release cleanup. - All functionality must be operable by keyboard. - Preserve visible focus indicators. - Use native semantic controls before custom controls. - Images require meaningful alternative text when they convey information; decorative images should not create noise for assistive technology. - Form controls require programmatically associated labels. - Heading hierarchy must reflect document structure. - Do not rely on color alone to communicate meaning. - Respect reduced-motion preferences when animation is introduced. - Layouts must remain usable across mobile and desktop widths and under text zoom. ## 5. Content and blog standards - Application code, schema, validation, and rendering remain source-controlled and deploy reproducibly. - Managed post content is authored through the authenticated administration interface and stored as backed-up SQLite runtime data; it must not be edited directly in production database files. - Dates, titles, descriptions, canonical URLs, and other metadata should be explicit and machine-readable where appropriate. - External claims should be attributable when attribution materially helps the reader. - Draft or unpublished material must not be exposed through public APIs, pages, or the public deployment tree. - Personal or confidential information must not be published merely because it exists in repository history. ## 6. Security and privacy - Never commit secrets. This includes TLS private keys and anything under `/etc/letsencrypt`. - Keep the public attack surface minimal. - Escape or sanitize untrusted content before inserting it into HTML. - Avoid inline script where practical so a restrictive Content Security Policy remains feasible. - Third-party scripts, analytics, embeds, fonts, and trackers require an explicit reason to exist. - Do not expose server paths, credentials, internal addresses, or unnecessary infrastructure details in the deployed site. - Security-sensitive configuration belongs in server configuration or deployment tooling, not client-side JavaScript. ## 7. CSS and visual design - Design mobile-first and responsive. - Prefer reusable design tokens/custom properties for repeated values. - Avoid specificity escalation and `!important` except where clearly justified. - Components should degrade cleanly when JavaScript is unavailable unless JavaScript is fundamental to the feature. - Maintain readable line lengths, spacing, contrast, and typography. ## 8. JavaScript - Keep modules focused and dependencies explicit. - Prefer pure/deterministic functions for logic that can be separated from DOM interaction. - Do not silently swallow errors. - Validate external or structured data before relying on it. - Avoid global mutable state where a smaller scope is practical. - Do not leak implementation details or sensitive data into browser logs. ## 9. Testing and validation Every change should receive validation proportional to its risk. At minimum before deployment: - Verify HTML/CSS/JavaScript loads without browser-console errors. - Exercise changed behavior manually at mobile and desktop widths. - Exercise keyboard navigation for changed interactive behavior. - Check internal links and asset paths affected by the change. - Run automated tests and validation when present. Logic with meaningful branching or transformation should have automated tests. Regression fixes should add a regression test when practical. ## 10. Performance - Optimize images for their rendered use. - Avoid shipping unused JavaScript or CSS. - Prefer browser-native capabilities over dependencies for trivial functionality. - Defer non-critical resources when appropriate. - Treat performance regressions as defects when they materially affect usability. ## 11. Deployment - Deployment must be reproducible from repository source. - Validate before modifying production. - Keep deployment steps documented in `docs/deployment.md`. - Production should be recoverable by redeploying a known-good revision rather than manually reconstructing files. - HTTP must redirect to HTTPS. - Certificate renewal must remain automated and periodically verifiable. - Do not make a production change that exists only on the server unless it is an emergency; reconcile emergency changes back into source/configuration documentation immediately. ## 12. Documentation Documentation changes are part of implementation, not optional follow-up. Update documentation whenever a change affects setup, architecture, operation, deployment, content workflow, or developer expectations. Commands in documentation should be copy/pasteable and reflect the supported path. ## 13. AI-assisted contributions AI assistance does not lower the bar for correctness, review, security, attribution, or testing. AI-generated changes must satisfy these same standards and must be reviewed as code, not accepted merely because they were generated. No special AI attribution is *required* unless a separate legal, licensing, or project requirement calls for it. One may be given at the descretion of the developer. ## 14. Definition of done A change is done when: - the requested behavior/content is complete; - relevant standards are satisfied; - tests and validation pass; - accessibility and responsive behavior have been considered; - no secrets or unintended content are included; - documentation is current; and - the resulting source can be deployed reproducibly.