Repository Structure

Repository & Naming Guidelines

This document defines the structural conventions, naming principles, and repository-level best practices used across all EncoSoft-managed GitHub projects.

---

📁 Repository Layout

Each repository should follow a minimal and modular structure:

.
├── .github/                # Meta files (README, ISSUE_TEMPLATE, etc.)
├── docs/                   # Markdown-based documentation
├── src/                    # Source code or implementation root
├── tests/                  # Test units and validation tools
├── assets/                 # Icons, images, UI samples
└── README.md               # Main entry documentation

• .github/: This directory contains repository-specific meta-files such as README.md (for individual repositories), ISSUE_TEMPLATE.md, PULL_REQUEST_TEMPLATE.md, and other configuration files related to GitHub features (e.g., GitHub Actions workflows). For the organization-level profile, refer to the root .github repository.
• docs/: Houses more extensive, markdown-based documentation that is not suitable for the main README.md.
• src/: The primary location for all source code or implementation files.
• tests/: Dedicated to unit, integration, and end-to-end tests for the corresponding source code.
• assets/: Stores images, icons, UI samples, and other static media assets used within the repository's documentation or related projects.
• README.md: The main entry point for each repository, providing a concise overview, purpose, and quick links.

---

🔤 Naming Conventions

Repository Names

• Use lowercase with hyphens (kebab-case):
  • ✅ apple-app-ios-template
  • ✅ image-processing-utils
• Prefix according to category if necessary:
  • apple-app-ios- for Apple applications for iOS
  • encosoft-meta- for internal toolsets
  • infra- for infrastructure-related repositories (e.g., infra-aws-network, infra-kubernetes-config)
  • solution- for specific client or internal solutions (e.g., solution-factory-automation)

File & Directory Names

• Use either PascalCase or kebab-case, depending on context
• Avoid snake_case or inconsistent capitalization
• Examples for clarity:
  • src/MyFeature.cs, docs/api-reference.md
  • src/common-components/shared-controls.ts, tests/unit-tests/data-utils-test.py

Component Naming

• Interface: Prefix with I (e.g., IService, IConfig)
• Generic types: Use suffix T (e.g., ResultT, PayloadT)
• Boolean variables: Start with is, has, can for clarity
• Enums: Use PascalCase for enum types and values (e.g., StatusType.Pending)
• Constants: Use ALL_CAPS_WITH_UNDERSCORES (e.g., MAX_RETRIES, DEFAULT_TIMEOUT_SECONDS)

---

🧭 Commit Message Format

Use the conventional commit format:

type(scope): short description

[optional body with context, reasoning, or impact]

Examples:

feat(core): add initial plugin loader
fix(ui): resolve label alignment issue
refactor(api): migrate response schema

Common types: feat, fix, docs, refactor, test, chore, style, release

---

✅ Good Practices

This section outlines best practices for maintaining code quality, collaboration, and project health within EncoSoft repositories.

• Code Review: All significant code changes must undergo a peer code review process before merging. Focus on readability, maintainability, performance, and adherence to established coding standards.
• Testing: Write comprehensive unit and integration tests for new features and bug fixes. Ensure test coverage remains high to prevent regressions.
• Documentation: Maintain clear and up-to-date documentation for code, APIs, and system architecture. Refer to the Document Standards for guidelines.
• Dependency Management: Manage project dependencies carefully. Regularly update libraries to their latest stable versions, and address any security vulnerabilities promptly.
• Branching Strategy: Utilize a clear branching strategy (e.g., GitFlow, GitHub Flow) that aligns with the project's development cycle.
• Security: Prioritize security by following secure coding practices, conducting regular security audits, and addressing identified vulnerabilities.

---

🔗 Related Documents

• Document Standards
• Brand Identity Guide

---

* Last updated: 2025-06-17