Skip to content

Contributing to Famlab

Thank you for your interest in contributing to Famlab! This guide will help you understand our development process and documentation standards.

Documentation-First Development

We're currently in a documentation-first development phase. Before writing any code, we're defining the complete user experience and system architecture through documentation. This helps us validate ideas and scope before implementation.

Development Philosophy

Core Principles

  • Deploy once, use forever - Everything should aim at zero-maintenance after initial setup
  • MVP-focused - Build distributed backup networks completely before expanding features
  • Family-friendly - Solutions work for all technical skill levels in a household
  • Document first - Define user experience before implementation

Read more about our Principles on the dedicated page.

Documentation Framework

We follow the Diátaxis framework for organizing documentation:

  • Tutorials (docs/tutorials/) - Learning-oriented, step-by-step guides
  • How-to guides (docs/how-to/) - Problem-solving oriented, goal-focused
  • Reference (docs/reference/) - Information-oriented, comprehensive details
  • Explanation (docs/explanation/) - Understanding-oriented, clarifying concepts

When contributing documentation, consider which category best fits your content.

Architecture Decision Process

When to Write an ADR

Create an Architecture Decision Record (ADR) for:

  • Significant architectural choices - Technology selection, system boundaries
  • Design patterns - How components interact, data flow decisions
  • Deployment strategies - Hardware requirements, installation approaches
  • Scope decisions - What's included/excluded from MVP or releases

ADR Workflow

  1. Copy one of the templates from docs/reference/architecture-decisions/README.md
  2. Number sequentially - Use next available ADR number
  3. Write the ADR following the MADR template
  4. Get feedback through pull request review
  5. Update status when decision is finalized

See ADR process documentation for templates and examples.

Development Workflow

Current Phase: Documentation Development

  1. Identify gaps - Find missing or unclear documentation
  2. Write ADR if needed - Document any architectural decisions
  3. Follow Diátaxis - Place content in appropriate documentation category
  4. Focus on user experience - Document what users will actually do
  5. Validate through review - Ensure documentation serves user needs

Future Phase: Implementation

Once documentation is complete:

  1. Tests first - Write comprehensive tests before implementation
  2. Atomic commits - Each commit represents one logical change
  3. Zero maintenance - Every component must be "set and forget"
  4. MVP scope only - No feature creep beyond documented scope

Getting Started

  1. Read the architecture - Start with our Principles
  2. Check current ADRs - Review the architecture decisions
  3. Understand the MVP - Read about the first release's scope
  4. Follow getting started - Walk through our tutorial
  5. Set up your environment - Follow the steps in the source code's main README
  6. Get familiar with the testing principles - Check out our Testing Reference

Before Submitting Proposals

  1. Run tests locally: mise run test must pass
  2. Add tests for new features: Shell tests or console-test blocks
  3. Update documentation: Keep examples testable where appropriate
  4. Check test coverage: New CLI commands should have console-test examples

Questions and Discussion

  • Architecture questions - Open an issue to discuss before writing ADR
  • Documentation clarity - Suggest improvements to existing docs
  • Scope questions - Reference MVP document and existing ADRs
  • Implementation timing - Remember we're documentation-first right now

License

This project is licensed under the GNU Affero General Public License v3.0. By contributing, you agree that your contributions will be licensed under the same license.

Remember: We're building the documentation first to ensure we build the right thing. Every contribution helps validate our approach before we commit to code.