From 419a93837f96d1e44b34f8cebc03aef66758786c Mon Sep 17 00:00:00 2001 From: Le Hoang Nam Date: Fri, 12 Sep 2025 16:41:26 +0700 Subject: [PATCH] Revise overview document to enhance clarity and structure - Updated the title to "Overview & Purpose" for better context. - Refined the purpose section to emphasize the document's role as a central reference for game development workflows. - Introduced a new section outlining the document's scope and expected benefits for development teams, code delivery, and the organization. - Streamlined content by removing outdated sections and consolidating key workflow components. - Added clear headings and bullet points for improved readability and navigation. --- docs/01-overview.md | 144 +++++++++++++++++--------------------------- 1 file changed, 56 insertions(+), 88 deletions(-) diff --git a/docs/01-overview.md b/docs/01-overview.md index db4bc0e..99c38ca 100644 --- a/docs/01-overview.md +++ b/docs/01-overview.md @@ -3,104 +3,72 @@ id: 01-overview title: Overview --- -# Overview +# Overview & Purpose -## Purpose -This document provides comprehensive information about our development workflow, including GitFlow workflow management, CI/CD pipeline integration with Jenkins, Gitea repository management, release processes, and detailed setup instructions for all components. It serves as the central reference for developers to understand and implement our standardized development practices and workflows. +## Document Purpose -## Document Structure -The development workflow documentation is organized into the following main sections: +This development workflow document serves as the **central reference guide** for all developers involved in our **game development process**. It defines standardized practices, procedures, and guidelines to ensure consistency, efficiency, and high-quality delivery across all projects. -### 1. **GitFlow Workflow** -- Branching strategy and naming conventions -- Feature, develop, release, and hotfix branch workflows -- Pull request and code review processes +### Why This Document Exists +- **Game Development Standardization** → Provides uniform processes across projects. +- **Rapid Onboarding** → Helps new team members quickly learn workflows. +- **Quality Assurance** → Enforces practices that maintain technical and delivery standards. + +--- + +## Document Scope + +### What This Workflow Covers + +🔄 **Version Control & Branching Strategy** +- Git workflow and branching model for game development +- Branch naming conventions and protection rules - Merge strategies and conflict resolution +- Code versioning and change tracking -### 2. **Gitea Management** -- Repository setup and configuration -- User and team management -- Access control and permissions -- Webhook configuration for CI/CD integration -- Gitea Actions setup and configuration +🔍 **Code Review & Quality Assurance** +- Pull request process and review guidelines +- Code quality standards and best practices +- Automated testing and quality gates +- Security checks and compliance validation -### 3. **Jenkins CI/CD Pipeline** -- Jenkins server setup and configuration -- Pipeline job definitions and configurations -- Build, test, and deployment automation -- Integration with Gitea and other tools -- Monitoring and notification systems +📝 **Code Standards & Conventions** +- Coding style guidelines and formatting rules +- Naming conventions for variables, functions, and classes +- Documentation standards and comment requirements +- Code organization and structure guidelines +- Language-specific best practices and patterns -### 4. **Release Management** -- Release planning and versioning strategy -- Release branch creation and management -- Deployment procedures and environments -- Rollback strategies and emergency procedures -- Release notes and documentation +🚀 **Continuous Integration / Continuous Deployment (CI/CD)** +- Automated build and testing pipelines +- Game build automation for Web, Mobile, and Desktop platforms +- Deployment processes and environment management +- Rollback procedures and monitoring -### 5. **Setup and Configuration** -- Step-by-step setup instructions for Gitea -- Jenkins installation and configuration -- Gitea Actions setup and workflow configuration -- Environment-specific configurations -- Troubleshooting guides and common issues +--- -## Key Workflow Components +## Expected Benefits -### Development Cycle -1. **Feature Development**: Create feature branches from develop -2. **Code Review**: Submit pull requests for review and approval -3. **Integration**: Merge approved features into develop branch -4. **Release Preparation**: Create release branches from develop -5. **Testing & Deployment**: Automated testing and deployment via Jenkins -6. **Release**: Merge release branches to master and develop -7. **Hotfixes**: Emergency fixes directly from master branch +### For Development Teams +- **Faster Onboarding** → New members quickly understand workflows. +- **Consistent Code Quality** → Standardized reviews improve maintainability. +- **Reduced Conflicts** → Clear branching prevents merge issues. +- **Automated Quality Gates** → CI/CD pipelines catch issues early. +- **Code Consistency** → Shared conventions improve readability. +- **Faster Development** → Less decision overhead, smoother collaboration. -### Automation Benefits -- **Continuous Integration**: Automated builds and testing on every commit -- **Quality Gates**: Automated code quality checks and security scans -- **Deployment Automation**: Consistent and repeatable deployment processes -- **Monitoring**: Real-time feedback on build and deployment status +### For Code Delivery +- **Predictable Releases** → Structured CI/CD ensures reliable deployments. +- **Reduced Bugs** → Automated tests prevent regressions. +- **Faster Delivery** → Streamlined pipelines shorten release cycles. +- **Better Traceability** → Gitflow tracks all code changes. +- **Maintainable Code** → Consistency simplifies future updates. +- **Reduced Technical Debt** → Standards discourage poor practices. -## How to Use This Documentation +### For the Organization +- **Scalability** → Processes work across projects and teams +- **Code Reusability** → Shared practices support component reuse +- **Knowledge Retention** → Documented processes preserve expertise +- **Risk Reduction** → Clear workflows reduce release and operational risks -### For Developers -- Follow the GitFlow workflow for all code changes -- Use the setup guides to configure your local development environment -- Reference the release procedures when preparing for releases -- Check troubleshooting guides for common issues -- Understand how your code changes trigger CI/CD pipelines -- Learn how to work with Gitea repositories and pull requests -- Familiarize yourself with release processes and versioning - -## Contributing to Workflow Documentation - -To contribute improvements or updates to the workflow documentation: - -1. Clone the repository: `git clone [repository-url]` -2. Create a feature branch: `git checkout -b feature/workflow-improvement` -3. Make your changes following the established documentation structure -4. Ensure all setup instructions are tested and verified -5. Commit and push your changes with descriptive commit messages -6. Open a Pull Request with detailed description of changes -7. Request review from relevant team members - -:::note -Please ensure all workflow changes are tested in a staging environment before updating production documentation. -::: - -:::tip -Keep documentation up-to-date with actual workflow implementations. Outdated documentation can cause confusion and workflow issues. -::: - -## Getting Started - -If you're new to our development workflow: - -1. Start with the **GitFlow Workflow** section to understand our branching strategy -2. Review **Gitea Management** for repository access and permissions -3. Check **Jenkins Setup** for CI/CD pipeline understanding -4. Familiarize yourself with **Release Management** procedures -5. Use **Setup Guides** to configure your development environment - -For immediate assistance, contact the DevOps team or refer to the troubleshooting sections in each component's documentation. \ No newline at end of file +---