Global Conventions

Organize your repository by establishing a consistent directory structure for source code, configuration, documentation, and dependencies. Apply naming conventions to files and folders, standardize commit message formats, define branching strategies (e.g., feature/bugfix naming), and document standards in a README or contributing guide. This reduces onboarding time and improves team collaboration.

Use descriptive commit messages that explain the why and what of changes. Adopt a branching strategy with consistent naming—like feature/user-settings or bugfix/login-error—to clarify intent. Create pull request templates and document review processes. These practices enable code review efficiency and make project history searchable and meaningful.

Store environment variables and secrets separately from source code using configuration files or secret management tools. Never commit credentials to version control. Document required environment variables in a .env.example file and establish conventions for naming and accessing secrets consistently across development, testing, and production environments.

Consistent project structure reduces cognitive load during onboarding, enables developers to locate files intuitively, and facilitates automated tooling. Standardized patterns for dependency management, testing, and documentation make collaboration seamless and prevent confusion when team members switch between repositories.

A README should document project purpose, setup instructions, dependency requirements, how to run tests, branching conventions, and contribution guidelines. Clear documentation accelerates onboarding, reduces repetitive questions, and establishes shared understanding of project conventions and governance expectations.

Define testing requirements in contribution guidelines, specify test coverage thresholds, and document the code review process including approval workflows. Use automated checks in pull requests to enforce standards. Consistent testing and review practices catch issues early and maintain code quality across the project.