diff --git a/README.md b/README.md index 050da1742..df2794937 100644 --- a/README.md +++ b/README.md @@ -36,22 +36,6 @@ ng build This will compile your project and store the build artifacts in the `dist/` directory. By default, the production build optimizes your application for performance and speed. -## Running unit tests - -To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command: - -```bash -ng test -``` - -## Running end-to-end tests - -For end-to-end (e2e) testing, run: - -```bash -ng e2e -``` - Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs. ## Additional Resources diff --git a/docs/arch.md b/docs/arch.md new file mode 100644 index 000000000..7da5851f9 --- /dev/null +++ b/docs/arch.md @@ -0,0 +1,58 @@ +# πŸ“‚ Folder Structure + +Project based on principle **Feature-based Architecture**, this approach provides reusable and consistant +features across the application. + +```bash +πŸ“¦ src/ + β”œβ”€β”€ πŸ“‚ features/ # ΠšΠ°Ρ‚Π°Π»ΠΎΠ³ Ρ–Π· Ρ„ΡƒΠ½ΠΊΡ†Ρ–ΠΎΠ½Π°Π»ΡŒΠ½ΠΈΠΌΠΈ модулями + β”‚ β”œβ”€β”€ πŸ“‚ feature-name/ + β”‚ β”‚ β”œβ”€β”€ πŸ“‚ feature.component.ts/html/scss # Component with template and styles, and base logic file + β”‚ β”‚ β”œβ”€β”€ πŸ“‚ feature-service.ts # Service or Facade to provide data for NGXS + β”‚ β”‚ β”œβ”€β”€ πŸ“‚ feature.store.ts # NGXS Store for feature + β”‚ β”‚ β”œβ”€β”€ πŸ“‚ feature.entitity.ts # Feature Interface for data, Types, Enums + β”‚ β”‚ β”œβ”€β”€ πŸ“‚ feature.guards.ts # Guard's for feature routing and permissions + β”‚ β”‚ β”œβ”€β”€ πŸ“‚ feature.resolvers.ts # Resolvers for data fetching and preloading + β”‚ β”‚ β”œβ”€β”€ πŸ“‚ feature.utils.ts # Additinal utils for feature (formBuilders, converters, mappers) + β”‚ β”‚ β”œβ”€β”€ feature.module.ts # Optional, if standalone + β”‚ β”‚ β”œβ”€β”€ feature.routing.ts # Export of standalone components by path + β”‚ + β”œβ”€β”€ πŸ“‚ core/ # Base module for global services, components, and state + β”‚ β”œβ”€β”€ πŸ“‚ services/ # Global services (API, Auth, LocalStorage) + β”‚ β”œβ”€β”€ πŸ“‚ components/ # Global components (Header, Footer, Sidebar) + β”‚ β”œβ”€β”€ πŸ“‚ store/ # Core state management (Auth, Settings, Router) + β”‚ β”œβ”€β”€ core.module.ts # Optional, but must have a provider for core. + β”‚ + β”œβ”€β”€ πŸ“‚ shared/ # Shared module for common components, directives, pipes, and services + β”‚ β”œβ”€β”€ πŸ“‚ ui/ # Shared UI components (Button, Input, Modal), or wrappers for 3rd party + β”‚ β”œβ”€β”€ πŸ“‚ directives/ # Shared Directives (ClickOutside, Draggable) + β”‚ β”œβ”€β”€ πŸ“‚ pipes/ # Shared Pipes (Filter, Sort, Format) + β”‚ β”œβ”€β”€ πŸ“‚ services/ # Services, Facades for shared logic (Http, LocalStorage) + β”‚ β”œβ”€β”€ πŸ“‚ store/ # Shared State management (Settings, Theme, Language) + β”‚ + β”œβ”€β”€ app.routes.ts # General Entry point for routing + β”œβ”€β”€ main.ts # Providers Setup and Bootstrap + β”œβ”€β”€ package.json # Dependencies and Scripts + + +--- +``` + +## πŸš€ Dynamic File Generation (Schematics) + +Use Angular CLI to generate new feature components, services, and modules. + +```sh +ng generate component feature-name/components/new-component + +### πŸ“Œ Other Schematics: + +| **Entity** | **Command** | +|--------------|----------------------------------------------| +| πŸ“Œ **Service** | `ng g s feature-name/services/new-service` | +| πŸ“¦ **Module** | `ng g m feature-name` | +| πŸ” **Guard** | `ng g g feature-name/guards/auth-guard` | +| πŸ”„ **Pipe** | `ng g p shared/pipes/currency-format` | +| ✨ **Directive** | `ng g d shared/directives/highlight` | + + diff --git a/docs/git-convention.md b/docs/git-convention.md new file mode 100644 index 000000000..013ce2f61 --- /dev/null +++ b/docs/git-convention.md @@ -0,0 +1,129 @@ +# πŸ“Œ Git Branch Naming Convention (Aligned with Angular Guideline) + +# πŸ“– Introduction + +### To maintain a clean commit history and improve team collaboration, we follow Angular Conventional Commits in our Git branch naming. This approach makes it easy to identify change types and automate release processes. + +# πŸš€ Branch Naming Format + +### The branch name should follow the format: + +```bash +/- + +type – type of change (inspired by Angular Commit Message Convention). + +issue-id – task or issue ID (optional but recommended). + +short-description – a brief description of the change. + +``` + +# πŸ“Œ Available Types (type) + +### We use the following types to categorize changes: +```bash +| Type --- Purpose +| feat --- Adding a new feature +| fix --- Fixing a bug or issue +| refactor --- Code refactoring without changing functionality +| perf --- Performance improvements +| test --- Adding or updating tests +| chore --- Updating configurations, tools, or dependencies +| docs --- Updating or adding documentation +| style --- Code style changes (formatting, indentation, comments) +| ci --- Changes in CI/CD pipeline +| build --- Updates in build process or dependencies +| revert --- Reverting previous changes +``` + +# πŸ“ Branch Naming Examples + +### Here are some examples of branch names: +```bash +* feat/1234-add-user-authentication +* fix/5678-fix-login-bug +* refactor/4321-optimize-api-calls +* docs/7890-update-readme +* test/8765-add-e2e-tests-for-dashboard + +``` +# πŸ›  Example of Creating a Branch: + +### To create a new branch, use the following command: +```bash +git checkout -b feat/1234-add-user-authentication + +``` + +# πŸ† Best Practices + +* βœ… Use short and clear descriptions in branch names. +* βœ… Follow a consistent style across all branches for better project structure. +* βœ… Avoid redundant words, e.g., fix/1234-fix-bug (the word "fix" is redundant). +* βœ… Use kebab-case (- instead of _ or CamelCase). +* βœ… If there is no issue ID, omit it, e.g., docs/update-contributing-guide. + +# πŸ”— Additional Resources + +**Conventional Commits**: https://www.conventionalcommits.org + +**Angular Commit Guidelines**: https://github.com/angular/angular/blob/main/CONTRIBUTING.md + +**Git Flow**: https://nvie.com/posts/a-successful-git-branching-model/ + +# This branch naming strategy ensures better traceability and improves commit history readability. πŸš€ + +# πŸ“ Commit Message Formatting + +To ensure clear and structured commit messages, we follow the Conventional Commit format: + +πŸ”Ή **Commit Message Structure** + +```bash +(): + +[optional body] + +[optional footer] + +type – The type of change (e.g., feat, fix, docs, style, etc.). + +scope – A short context describing the part of the project affected (optional but recommended). + +short description – A concise summary of the change (in imperative form, e.g., "fix login bug"). + +body – A more detailed explanation of the change (if necessary). + +footer – Additional metadata, e.g., references to issues (Closes #123). +``` + +# πŸ“Œ Example Commit Messages + +```bash + +feat(auth): add user authentication flow + +Implemented login, registration, and session handling. +Closes #1234. + +fix(ui): resolve button alignment issue + +Fixed misalignment of buttons in the settings panel. + +docs(readme): update installation instructions + +Clarified step-by-step setup instructions for the project. + +``` + +# πŸ”— Additional Resources + +Conventional Commits: https://www.conventionalcommits.org + +Angular Commit Guidelines: https://github.com/angular/angular/blob/main/CONTRIBUTING.md + +Git Flow: https://nvie.com/posts/a-successful-git-branching-model/ + +This branch naming and commit message strategy ensures better traceability and improves commit history readability. πŸš€ +