How-to

This section provides how-tos for developers to standardize and efficiently perform certain tasks relevant to the project. Any recurring developer that’s either documented here by the development team or can be added by yourself.

What to write?
Intention

Intention of this section is to provide guides for developers on how to perform certain tasks relevant for the project. This should help improve productivity and consistency in the development process. Be concise and to the point, assume the reader is competent in technology and tools used in the project. See How-to guides in diataxis for more information.

What to include

  • First steps when joining the project

    • How to set up the development environment

    • How to get access to the project resources

  • How to contribute to the project

    • Review process

    • Coding standards

    • Testing

    • Definition of Done

  • How to deploy the project

  • How to roll back a deployment

  • How to perform maintenance routines

  • How to debug the project or the running system

External resources
Example 1. Dependency Maintenance Routine Guide

Dependency Maintenance Routine Guide

This section provides a checklist for managing dependency updates in the software project. Regular maintenance ensures the incorporation of improvements, security fixes, and new features while maintaining system stability. Following a structured routine enables smooth handling of dependency updates and reduces technical debt.

Process Overview:

  1. Review Merge Requests by Dependabot / Renovate:

    • Check the changes proposed in the MR, including diff and commit messages.

    • Understand the context and impact of the updates.

  2. Dependency Updates:

    • Verify the list of updated dependencies and their version changes.

    • Review release notes for breaking changes, deprecations, or relevant fixes.

  3. Assignment and Ownership:

    • Assign the MR to yourself or the appropriate team member for detailed review and feedback.

  4. Testing Updates:

    • Test changes locally or in a staging environment to ensure compatibility.

    • Use automated pipelines for regression testing where applicable.

  5. Pipeline Validation:

    • Verify the execution of pipelines and resolve any errors.

    • Regularly monitor nightly tests for hidden issues.

  6. Merge Changes:

    • Merge updates once testing and reviews are complete.

    • Follow project-specific commit message guidelines.

  7. Dockerfile and CI Images:

    • Check and update Dockerfiles for base images and tools.

    • Test and verify new image builds before deployment.

  8. Security Considerations:

    • Prioritize and assess the impact of security fixes.

    • Coordinate urgent releases for high-severity vulnerabilities.

  9. Helm Charts and Falco Rules:

    • Review changes in Helm charts and configuration.

    • Test new or updated Falco rules and resolve false positives.

  10. Monitoring Post-Update:

    • Monitor for new errors or events caused by updates.

    • Address issues promptly and iterate as needed.