From a024f10257d90e69cd626975d7c9844641ff40dd Mon Sep 17 00:00:00 2001 From: Mo2Hefny Date: Sun, 29 Dec 2024 14:37:17 +0200 Subject: [PATCH] feat: Add coding guidelines, testing guidelines, and architecture documentation --- README.md | 128 ++++++++++++++++++++++++++---- docs/ARCHITECTURE.md | 130 +++++++++++++++++++++++++++++++ docs/CODING_GUIDELINES.md | 48 ++++++++++++ docs/CONTRIBUTING.md | 133 ++++++++++++++++++++++++++++++++ docs/TESTING.md | 158 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 584 insertions(+), 13 deletions(-) create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/CODING_GUIDELINES.md create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/TESTING.md diff --git a/README.md b/README.md index 92bf61bf..feb069e0 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,135 @@ -# telware_cross_platform +# Telware Cross-Platform Team Repository -[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=TelwareSW_telware_cross_platform&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=TelwareSW_telware_cross_platform) [![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=TelwareSW_telware_cross_platform&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=TelwareSW_telware_cross_platform) [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=TelwareSW_telware_cross_platform&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=TelwareSW_telware_cross_platform) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=TelwareSW_telware_cross_platform&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=TelwareSW_telware_cross_platform) [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=TelwareSW_telware_cross_platform&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=TelwareSW_telware_cross_platform) [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=TelwareSW_telware_cross_platform&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=TelwareSW_telware_cross_platform) -A new Flutter project. +Welcome to the **Telware Cross-Platform Team's** repository! This project is part of the Telware initiative to recreate the Telegram app. Our team is responsible for building the **Flutter-based cross-platform implementation**, ensuring seamless functionality across Android, iOS, and other supported devices. + +## Table of Contents + +1. [Project Overview](#project-overview) +2. [Setup Instructions](#setup-instructions) +3. [Project Structure](#project-structure) +4. [Development Guidelines](#development-guidelines) +5. [Testing](#testing) +6. [Contributing](#contributing) +7. [License](#license) +8. [Additional Documentation](#additional-documentation) + +--- + +## Project Overview + +This repository contains the cross-platform codebase developed using Flutter. Our responsibilities include: + +- Building the core UI and app logic. +- Ensuring feature parity across platforms (Android, iOS). +- Collaborating with Backend, Frontend, DevOps, and Testing teams. +- Delivering a high-quality, performant, and reliable application. + +For a detailed understanding of the project workflow, refer to [docs/PROJECT_FLOW.md](docs/PROJECT_FLOW.md). + +## Setup Instructions + +### Prerequisites + +- **Flutter SDK**: Version `3.24.3` ([Installation Guide](https://docs.flutter.dev/get-started/install)) +- **Dart SDK**: Bundled with Flutter +- **Development Environment**: + - Android Studio (for Android builds) +- **Access to Backend Services**: Contact the backend team for API credentials and documentation. + +### Steps to Run the Project + +1. Clone the repository: + ```bash + git clone https://github.com/TelwareSW/telware_cross_platform.git + cd telware_cross_platform + ``` + +2. Install dependencies: + ```bash + flutter pub get + ``` + +3. Run the app on a connected device or emulator: + ```bash + flutter run + ``` + +4. To build platform-specific packages: + - **Android**: `flutter build apk` + - **iOS**: `flutter build ios` + +--- + +## Project Structure + +```plaintext +. +├── lib/ # Core application code +│ ├── components/ # Reusable UI components +│ ├── screens/ # Screens and page-level widgets +│ ├── services/ # Backend API integrations and business logic +│ ├── utils/ # Utility functions and helpers +│ └── main.dart # Application entry point +├── test/ # Unit and widget tests +├── docs/ # Documentation files +├── pubspec.yaml # Flutter dependencies configuration +└── README.md # Project overview and setup +``` --- -## :bar_chart: Project Flow +## Development Guidelines -For a detailed overview of our project's branching strategy, commit conventions, and overall workflow, please refer to the [PROJECT_FLOW.md](./docs/PROJECT_FLOW.md) document. +- **Coding Standards**: Follow the guidelines defined in [docs/CODING_GUIDELINES.md](docs/CODING_GUIDELINES.md). +- **Branching Strategy**: Use feature branches and maintain a linear Git history. Refer to [docs/PROJECT_FLOW.md](docs/PROJECT_FLOW.md). +- **Commit Messages**: Use the [Conventional Commits](https://www.conventionalcommits.org/) format. --- -## Getting Started +## Testing + +1. Run unit tests: + ```bash + flutter test + ``` + +2. Run integration tests: + ```bash + flutter drive --target=test_driver/app.dart + ``` + +For more details, refer to [docs/TESTING.md](docs/TESTING.md). -This project is a starting point for a Flutter application. +--- + +## Contributing + +We welcome contributions from all team members! To contribute: + +1. Fork the repository. +2. Create a feature branch: `git checkout -b feature/your-feature`. +3. Commit your changes: `git commit -m "feat: your feature description"`. +4. Push to your branch: `git push origin feature/your-feature`. +5. Submit a pull request. + +Refer to [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for more information. + +--- -A few resources to get you started if this is your first Flutter project: +## Additional Documentation -- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab) -- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook) +- [Architecture Overview](docs/ARCHITECTURE.md) +- [Contributing Guidelines](docs/CONTRIBUTING.md) +- [Testing Guide](docs/TESTING.md) +- [Coding Standards](docs/CODING_GUIDELINES.md) +- [Project Flow](docs/PROJECT_FLOW.md) -For help getting started with Flutter development, view the -[online documentation](https://docs.flutter.dev/), which offers tutorials, -samples, guidance on mobile development, and a full API reference. +For questions or further assistance, feel free to reach out via the project Slack channel or raise an issue in this repository. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 00000000..12ea0e7b --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,130 @@ +# Telware Cross-Platform Architecture + +This document provides a detailed overview of the architecture of the Telware Cross-Platform application. It complements the other documentation files in the `docs/` folder, including: + +- [README.md](../README.md): Project overview and getting started guide. +- [CODING_GUIDELINES.md](./CODING_GUIDELINES.md): Coding standards and conventions. +- [CONTRIBUTING.md](./CONTRIBUTING.md): Guidelines for contributing to the project. +- [PROJECT_FLOW.md](./PROJECT_FLOW.md): Development workflow and branching strategy. +- [TESTING.md](./TESTING.md): Testing strategy and best practices. + +## Overview + +The Telware Cross-Platform application is developed using [Flutter](https://flutter.dev/), enabling seamless deployment across multiple platforms, including: + +- **Mobile:** Android, iOS +- **Web:** Browser-based deployment +- **Desktop:** Linux, macOS, and Windows + +The use of a unified codebase ensures consistency in functionality, design, and performance across these platforms. + +## Project Structure + +The repository is organized to separate platform-specific and shared code, promoting modularity and ease of maintenance. + +### **Platform-Specific Directories** + +- **`android/`**: Android-specific configurations and native code. +- **`ios/`**: iOS-specific configurations and native code. +- **`web/`**: Web-specific configurations such as `index.html`. +- **`linux/`**, **`macos/`**, **`windows/`**: Configurations and native integrations for desktop platforms. + +### **Shared Directory** + +- **`lib/`**: Core Dart codebase shared across platforms: + - **UI Components:** Widgets for a consistent user interface. + - **Business Logic:** State management and application logic. + - **Services:** API integrations, database interactions, etc. + - **Utils:** Helper functions and utilities. + +## Key Architectural Features + +### **Flutter Framework** + +Flutter provides a declarative UI framework that enables: + +- **Hot Reload:** Rapid feedback during development. +- **Customizability:** Native performance with platform-specific customization. +- **Cross-Platform Consistency:** Shared design system and behavior. + +### **State Management** + +State management solutions like Provider, Riverpod, or Bloc are used to: + +- Ensure scalability for complex features. +- Improve code reusability and modularity. +- Maintain application state efficiently. + +### **Platform Channels** + +Flutter's platform channels enable interaction between Dart and native code for features like: + +- Accessing device hardware (e.g., camera, GPS). +- Using platform-specific APIs (e.g., Android's Intents, iOS's Core Data). + +### **Modular Design** + +- Separation of concerns is achieved through modules for UI, services, and utilities. +- Modules facilitate easier testing, debugging, and development. + +## Development Workflow + +Refer to [PROJECT_FLOW.md](./PROJECT_FLOW.md) for a detailed explanation of the development workflow. Key highlights: + +- **Branching Strategy:** + - `main`: Production-ready code. + - `develop`: Latest stable development code. + - `feature/` and `bugfix/` branches for individual changes. +- **CI/CD Pipelines:** Automate testing and deployment to ensure quality. + +## Quality Assurance + +### **Testing** + +The project follows rigorous testing practices as described in [TESTING.md](./TESTING.md): + +- **Unit Tests:** Validate individual components and logic. +- **Widget Tests:** Ensure UI behaves as expected. +- **Integration Tests:** These are provided by our dedicated testing team, who maintain a separate repository to ensure comprehensive validation of the application in real-world scenarios. + +### **Code Quality** + +- Adheres to the [coding guidelines](./CODING_GUIDELINES.md). +- Code reviews are mandatory for all pull requests. + +### **Security** + +- Sensitive data is managed using secure storage solutions. +- Regular dependency audits ensure the integrity of third-party libraries. + +## Setting Up the Project + +Follow these steps to set up the project locally: + +1. Clone the repository: + ```bash + git clone https://github.com/TelwareSW/telware_cross_platform.git + ``` + +2. Navigate to the project directory: + ```bash + cd telware_cross_platform + ``` + +3. Fetch dependencies: + ```bash + flutter pub get + ``` + +4. Run the application on your desired platform: + ```bash + flutter run + ``` + +## Future Improvements + +- Advanced state management for enhanced scalability. +- Deeper integration of platform-specific features. +- Increased test coverage for critical modules. + +For more details, explore the other documentation files in the `docs/` folder or visit the [repository](https://github.com/TelwareSW/telware_cross_platform). diff --git a/docs/CODING_GUIDELINES.md b/docs/CODING_GUIDELINES.md new file mode 100644 index 00000000..df957285 --- /dev/null +++ b/docs/CODING_GUIDELINES.md @@ -0,0 +1,48 @@ +# Coding Guidelines + +To ensure consistency and maintainability across the project, please follow these coding standards: + +## General Guidelines + +- Write clean and readable code. +- Follow the [Effective Dart](https://dart.dev/guides/language/effective-dart) guidelines. +- Avoid hardcoding values; use constants or configuration files. +- Ensure all code changes are tested before committing. + +## File and Folder Organization + +- Group related files together (e.g., components, screens, services). +- Keep files small and focused; a single file should ideally handle one responsibility. +- Use descriptive and consistent file and folder names in `snake_case`. + +## Naming Conventions + +- **Classes**: Use `PascalCase` (e.g., `UserModel`, `MainScreen`). +- **Variables**: Use `camelCase` (e.g., `userName`, `isLoggedIn`). +- **Constants**: Use `UPPER_SNAKE_CASE` (e.g., `MAX_RETRY_COUNT`). + +## Code Comments + +- Write meaningful comments explaining the “why” behind the logic, not the “what.” +- Document all public methods and classes using DartDoc. + ```dart + /// Calculates the total price of items in the cart. + double calculateTotalPrice(List items) { + ... + } + ``` + +## Flutter-Specific Guidelines +- Use widgets efficiently; prefer `const` constructors where possible. +- Separate business logic from UI using patterns like Provider, or Riverpod. +- Avoid nesting widgets deeply; extract them into reusable components. + +## Git Commit Guidelines +- Use descriptive commit messages (e.g., `feat: add login functionality`). +- Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. + +## Code Reviews +- All pull requests must be reviewed and approved before merging. +- Address all comments from reviewers before marking a PR as ready. + +By adhering to these guidelines, we ensure a high standard of quality and a codebase that's easier to maintain and scale. \ No newline at end of file diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 00000000..e90a5980 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,133 @@ +# Contributing Guidelines + +Thank you for your interest in contributing to the **Telware Cross-Platform** project! This document outlines the process for contributing effectively and ensuring smooth collaboration across teams. + +## Table of Contents + +1. [Getting Started](#getting-started) +2. [Development Workflow](#development-workflow) +3. [Submitting Changes](#submitting-changes) +4. [Code Reviews](#code-reviews) +5. [Referencing Documentation](#referencing-documentation) +6. [Reporting Issues](#reporting-issues) +7. [Community Standards](#community-standards) + +--- + +## Getting Started + +To contribute, follow these initial steps: + +1. **Familiarize Yourself with the Project**: + - Read the [README.md](../README.md) to understand the project's purpose and structure. + - Review the [PROJECT_FLOW.md](PROJECT_FLOW.md) for an overview of how features are planned, developed, and delivered. + +2. **Set Up Your Environment**: + - Follow the [Setup Instructions](../README.md#setup-instructions) in the main README. + - Ensure you have all dependencies and tools installed. + +3. **Fork and Clone the Repository**: + - Fork the repository to your GitHub account. + - Clone your forked repository locally: + ```bash + git clone https://github.com/your-username/telware_cross_platform.git + cd telware_cross_platform + ``` + +4. **Create a Branch**: + - Use a meaningful name for your branch that reflects the purpose of your work: + ```bash + git checkout -b feature/your-feature-name + ``` + +--- + +## Development Workflow + +1. **Follow Coding Standards**: + - Adhere to the [Coding Guidelines](CODING_GUIDELINES.md) to ensure code consistency and readability. + - Use proper naming conventions, structure files appropriately, and write meaningful comments. + +2. **Write Tests**: + - All new features and bug fixes must include corresponding tests. + - Run existing tests to ensure your changes do not break functionality: + ```bash + flutter test + ``` + +3. **Document Your Work**: + - Update relevant documentation in the `docs/` folder if your changes introduce new functionality or modify existing behavior. + - Update the [README.md](../README.md) if your changes impact the setup process or project structure. + +4. **Commit Changes**: + - Use descriptive commit messages that follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: + ```bash + git commit -m "feat: add user authentication logic" + ``` + +--- + +## Submitting Changes + +1. **Push Your Branch**: + - Push your branch to your forked repository: + ```bash + git push origin feature/your-feature-name + ``` + +2. **Open a Pull Request**: + - Navigate to the main repository and open a pull request to the `develop` branch. + - In the pull request description: + - Clearly explain the purpose of your changes. + - Reference any related issues (e.g., `Closes #123`). + - Mention relevant documents, such as `PROJECT_FLOW.md` or `CODING_GUIDELINES.md`, if applicable. + +3. **Respond to Feedback**: + - Be responsive to reviewers' comments and make necessary updates promptly. + - Ensure all requested changes are addressed before marking the pull request as ready. + +--- + +## Code Reviews + +All pull requests undergo a code review to maintain high-quality standards. During reviews, ensure that you: + +- Address all reviewer comments thoughtfully. +- Cross-check your changes with the [Coding Guidelines](CODING_GUIDELINES.md). +- Verify the alignment of your changes with the [PROJECT_FLOW.md](PROJECT_FLOW.md). + +--- + +## Referencing Documentation + +Leverage the following documents to guide your contributions: + +- [README.md](../README.md): For understanding project structure and setup instructions. +- [PROJECT_FLOW.md](PROJECT_FLOW.md): For insights into the development process and workflows. +- [CODING_GUIDELINES.md](CODING_GUIDELINES.md): For coding standards and best practices. + +Referencing these resources ensures your contributions are aligned with team expectations and project goals. + +--- + +## Reporting Issues + +If you encounter bugs, want to suggest new features, or have questions: + +1. Check the [Issues](https://github.com/TelwareSW/telware_cross_platform/issues) tab to see if your concern is already addressed. +2. If not, open a new issue: + - Provide a clear and concise title. + - Include detailed steps to reproduce the issue, if applicable. + - Mention any relevant files or lines of code. + +--- + +## Community Standards + +We are committed to maintaining a welcoming and inclusive community. As a contributor, please: + +- Be respectful and constructive in discussions. +- Follow the guidelines outlined in [PROJECT_FLOW.md](PROJECT_FLOW.md) and [CODING_GUIDELINES.md](CODING_GUIDELINES.md). +- Collaborate openly and transparently with other team members. + +Thank you for contributing to the **Telware Cross-Platform** project! Together, we can create a high-quality application that meets user needs. diff --git a/docs/TESTING.md b/docs/TESTING.md new file mode 100644 index 00000000..ea902680 --- /dev/null +++ b/docs/TESTING.md @@ -0,0 +1,158 @@ +# Testing Guidelines + +This document outlines the testing process for the **Telware Cross-Platform** project. Proper testing ensures that our application is reliable, performant, and free of critical bugs. Follow these guidelines to maintain high standards across all features. + +## Table of Contents + +1. Overview +2. Testing Setup +3. Testing Types +4. Writing Tests +5. Running Tests +6. Debugging and Troubleshooting +7. Referencing Documentation + +--- + +## Overview + +Testing is a critical part of the development workflow. All code changes must include tests, and the tests must pass before merging into the `develop` branch. The testing strategy ensures compatibility across platforms and helps identify regressions early in the development process. + +For more details on the development workflow, refer to: +- [README.md](../README.md#testing) +- [PROJECT_FLOW.md](PROJECT_FLOW.md) + +--- + +## Testing Setup + +Before running or writing tests, ensure your environment is properly configured: + +### Prerequisites + +1. **Flutter SDK**: Install the latest version ([Setup Guide](https://docs.flutter.dev/get-started/install)). +2. **Dart SDK**: Included with the Flutter installation. +3. **Emulators/Devices**: + - Set up Android emulators and/or iOS simulators for integration tests. + +### Installing Dependencies + +Run the following command to install required testing dependencies: +``` +flutter pub get +``` + +--- + +## Testing Types + +We use multiple levels of testing to ensure application quality: + +1. **Unit Tests**: + - Validate individual functions, classes, or methods. + - Example: Testing a utility function in `lib/utils/`. + +2. **Widget Tests**: + - Verify the behavior and layout of individual widgets. + - Example: Ensuring the `LoginButton` component renders correctly and triggers actions as expected. + +3. **Integration Tests**: + - Test the application as a whole, including interactions between components and backend services. + - Example: Validating the complete login process with API calls. + +--- + +## Writing Tests + +Tests are stored in the `test/` directory. Use the following structure to organize your tests: + +``` +test/ +├── core/ # Unit tests +├── features/ # Widget tests +└── integration/ # Integration tests +``` + +### Guidelines for Writing Tests + +1. **Follow Coding Standards**: + - Refer to [CODING_GUIDELINES.md](CODING_GUIDELINES.md) for consistent naming and formatting. + +2. **Use Descriptive Test Names**: + - Example: `test("should return a valid user object on successful login", () { ... });` + +3. **Mock Dependencies**: + - Use libraries like `mockito` to mock services or APIs during tests. + +4. **Focus on Edge Cases**: + - Test not just typical scenarios but also edge cases (e.g., network failures, invalid inputs). + +--- + +## Running Tests + +Use the following commands to execute tests: + +### Running Unit and Widget Tests + +To run all unit and widget tests: +``` +flutter test +``` + +### Running a Specific Test File + +To run tests in a specific file: +``` +flutter test test/unit/sample_test.dart +``` + +### Running Integration Tests + +Integration tests require a connected device or emulator. Start the tests with: +``` +flutter drive --target=test_driver/app.dart +``` + +--- + +## Debugging and Troubleshooting + +### Common Issues + +1. **Test Fails Unexpectedly**: + - Review error logs and ensure the latest dependencies are installed: + ``` + flutter pub get + ``` + +2. **Integration Test Fails on Emulator**: + - Confirm the emulator or device is running and has sufficient resources. + - Restart the emulator if needed. + +3. **Flaky Tests**: + - If a test passes intermittently, check for race conditions or dependency issues. + +### Tools for Debugging + +- **Flutter DevTools**: Use: +``` +flutter pub global activate devtools +``` +to install and run Flutter's debugging tools. + +- **Logs and Stack Traces**: Check detailed logs for root cause analysis. + +--- + +## Referencing Documentation + +For a seamless testing experience, leverage the following documents: + +- [README.md](../README.md#testing): High-level overview of the testing process. +- [PROJECT_FLOW.md](PROJECT_FLOW.md): Insights into the development lifecycle, including testing stages. +- [CODING_GUIDELINES.md](CODING_GUIDELINES.md): Best practices for writing clean and maintainable test code. + +--- + +By adhering to these guidelines, we can ensure the stability and quality of the **Telware Cross-Platform** application across all platforms and devices. If you encounter issues or need assistance, raise a query in the project Slack channel or file an issue in the repository.