@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/development/workflow.mdx

@@ -0,0 +1,914 @@
+---
+title: Development Workflow
+description: Day-to-day development workflow for the Blue Alba Platform including branching, changesets, testing, and pull requests
+---
+
+import { Steps, Aside, Card, CardGrid, Tabs, TabItem } from '@astrojs/starlight/components';
+
+This guide covers the day-to-day workflow for developing with the Blue Alba Platform, from creating features to submitting pull requests.
+
+## Development Process Overview
+
+The Blue Alba Platform follows a **feature branching workflow** with automated version management using **changesets**.
+
+```mermaid
+graph LR
+    A[Create Branch] --> B[Make Changes]
+    B --> C[Run Tests]
+    C --> D[Create Changeset]
+    D --> E[Commit & Push]
+    E --> F[Create PR]
+    F --> G[Review & Merge]
+    G --> H[Automatic Release]
+```
+
+---
+
+## Git Branching Strategy
+
+### Branch Hierarchy
+
+The repository uses the following branches:
+
+<CardGrid>
+  <Card title="develop" icon="rocket">
+    **Primary development branch**
+
+    - All feature branches branch from `develop`
+    - All PRs merge into `develop`
+    - Automatically deployed to development environment
+    - Always in a deployable state
+  </Card>
+
+  <Card title="main" icon="star">
+    **Production branch**
+
+    - Reflects production-ready code
+    - Only release commits merge here
+    - Automatically deployed to production
+    - Protected - no direct commits
+  </Card>
+
+  <Card title="feature/*" icon="puzzle">
+    **Feature branches**
+
+    - Created from `develop`
+    - One feature or bug fix per branch
+    - Naming: `feature/description` or `fix/description`
+    - Deleted after merge
+  </Card>
+
+  <Card title="rc/*" icon="seti:config">
+    **Release candidate branches**
+
+    - Created automatically by CI
+    - Naming: `rc/x.y.z`
+    - For final testing before production
+    - Merged to `main` after approval
+  </Card>
+</CardGrid>
+
+### Creating a Feature Branch
+
+<Steps>
+
+1. **Ensure you're on develop and up to date**
+
+   ```bash
+   git checkout develop
+   git pull origin develop
+   ```
+
+2. **Create a new feature branch**
+
+   ```bash
+   # For new features
+   git checkout -b feature/add-user-preferences
+
+   # For bug fixes
+   git checkout -b fix/login-redirect-issue
+
+   # For documentation
+   git checkout -b docs/update-api-guide
+   ```
+
+   <Aside type="tip">
+     **Branch Naming Convention**:
+     - Use lowercase with hyphens
+     - Prefix with `feature/`, `fix/`, `docs/`, or `chore/`
+     - Be descriptive but concise
+   </Aside>
+
+3. **Verify your branch**
+
+   ```bash
+   git branch
+   # Should show your new branch with an asterisk
+   ```
+
+</Steps>
+
+---
+
+## Making Changes
+
+### Working on Your Code
+
+Once you're on your feature branch, make your changes following these practices:
+
+#### 1. Make Focused Changes
+
+Keep your changes focused on a single feature or fix:
+
+```bash
+# Good - focused changes
+feature/add-user-preferences
+  - Add preferences API endpoint
+  - Add preferences UI component
+  - Add preferences tests
+
+# Bad - mixing unrelated changes
+feature/various-updates
+  - Add preferences
+  - Fix login bug
+  - Update documentation
+  - Refactor database queries
+```
+
+#### 2. Commit Frequently
+
+Make small, atomic commits with clear messages:
+
+```bash
+# Stage specific files
+git add src/services/preferences.service.ts
+git add src/controllers/preferences.controller.ts
+
+# Commit with descriptive message
+git commit -m "Add preferences service with CRUD operations"
+
+# Continue working
+git add src/dto/preferences.dto.ts
+git commit -m "Add preferences DTOs for validation"
+```
+
+<Aside>
+  **Commit Message Guidelines**:
+  - Use present tense ("Add feature" not "Added feature")
+  - Be specific and descriptive
+  - Keep first line under 72 characters
+  - Add body for complex changes
+</Aside>
+
+#### 3. Keep Your Branch Updated
+
+Regularly sync with `develop` to avoid merge conflicts:
+
+```bash
+# Fetch latest changes
+git fetch origin
+
+# Merge develop into your branch
+git merge origin/develop
+
+# Or rebase (if you prefer linear history)
+git rebase origin/develop
+```
+
+---
+
+## Testing Your Changes
+
+Before creating a PR, thoroughly test your changes.
+
+### Running Tests
+
+<Tabs>
+  <TabItem label="All Tests">
+    Run all tests across the entire monorepo:
+
+    ```bash
+    npx turbo test
+    ```
+
+    This runs tests in all packages and apps in parallel.
+  </TabItem>
+
+  <TabItem label="Specific Package">
+    Test a specific package or app:
+
+    ```bash
+    # Test a specific package
+    npx turbo test --filter=@bluealba/pae-core-lib
+
+    # Test a specific service
+    npx turbo test --filter=@bluealba/pae-nestjs-gateway-service
+
+    # Test a specific UI
+    npx turbo test --filter=@bluealba/pae-shell-ui
+    ```
+  </TabItem>
+
+  <TabItem label="Watch Mode">
+    Run tests in watch mode for active development:
+
+    ```bash
+    # In the package directory
+    cd packages/pae-core-lib
+    npm run test:watch
+
+    # Or for a service
+    cd apps/pae-habits-service
+    npm run test:watch
+    ```
+  </TabItem>
+
+  <TabItem label="Coverage">
+    Generate test coverage reports:
+
+    ```bash
+    # All packages
+    npx turbo test:coverage
+
+    # Specific package
+    cd packages/pae-core-lib
+    npm run test:coverage
+
+    # View coverage report
+    open coverage/lcov-report/index.html
+    ```
+  </TabItem>
+</Tabs>
+
+### Running Services Locally
+
+Test your changes with services running locally:
+
+<Steps>
+
+1. **Stop the Docker container** (if running)
+
+   ```bash
+   cd sandbox-product/pae-sandbox-local
+   docker-compose -f docker-compose-pae.yml stop pae-habits-service
+   ```
+
+   <Aside type="tip">
+     As an alternative to stopping the Docker container, you can keep the full Docker stack running and instead add a `serviceLocal` block to the module's definition in `modules.json`. When the bootstrap service is started with `LOCAL_MODE=true`, it will point the gateway at your locally running process (for example `localhost:4002`) without affecting the Docker-based configuration used by the rest of the team. See [Local Development Overrides](/_/docs/architecture/bootstrap/#local-development-overrides-servicelocal) for details.
+   </Aside>
+
+2. **Build your changes**
+
+   ```bash
+   cd bluealba-platform/apps/pae-habits-service
+   npm run build
+   ```
+
+3. **Run in development mode**
+
+   ```bash
+   npm run dev
+   ```
+
+   The service starts with hot reload enabled.
+
+4. **Test via the gateway**
+
+   ```bash
+   # Test API endpoint
+   curl -k https://localhost:9443/habits \
+     -H "Authorization: Bearer YOUR_JWT_TOKEN"
+   ```
+
+5. **View logs**
+
+   Watch the console output for errors and debug information.
+
+</Steps>
+
+### Running UIs Locally
+
+Test UI changes with hot reload:
+
+<Steps>
+
+1. **Start the UI in dev mode**
+
+   ```bash
+   cd bluealba-platform/apps/pae-shell-ui
+   npm run dev
+   ```
+
+   The UI typically runs on `http://localhost:8080`.
+
+2. **Access via browser**
+
+   Open `http://localhost:8080` and log in.
+
+3. **Make changes**
+
+   Edit source files - the UI automatically reloads.
+
+4. **Test with backend**
+
+   The dev server proxies API requests to the gateway.
+
+</Steps>
+
+<Aside type="note">
+  **Hot Reload**: Both services and UIs support hot reload. Change source files and see results immediately without manual restarts.
+</Aside>
+
+---
+
+## Building the Project
+
+Always build before creating a PR to catch compilation errors:
+
+### Full Build
+
+Build everything in the monorepo:
+
+```bash
+npx turbo build
+```
+
+Turborepo builds packages in dependency order and caches results.
+
+### Incremental Build
+
+Build only changed packages:
+
+```bash
+npx turbo build --filter=...[origin/develop]
+```
+
+This builds packages that changed since your branch diverged from `develop`.
+
+### Force Build
+
+Bypass cache and rebuild everything:
+
+```bash
+npx turbo build --force
+```
+
+### Build Verification
+
+Verify the build succeeded:
+
+```bash
+# Check for dist directories
+ls apps/pae-habits-service/dist
+ls packages/pae-core-lib/dist
+
+# Check for errors in output
+npx turbo build 2>&1 | grep -i error
+```
+
+---
+
+## Using Changesets
+
+**Changesets** are the most important part of the workflow. They track what changed and how to version packages.
+
+### What is a Changeset?
+
+A changeset is:
+- A **description** of what changed
+- A **list** of affected packages
+- A **version bump type** (major, minor, or patch) for each package
+
+### When to Create a Changeset
+
+Create a changeset when you make changes that affect:
+- Package functionality (new features, bug fixes, breaking changes)
+- Public APIs
+- Dependencies
+- Build outputs
+
+<Aside type="caution" title="Required">
+  **You MUST create a changeset before merging any PR** that changes packages or apps. PRs without changesets will fail CI checks.
+</Aside>
+
+### Creating a Changeset
+
+<Steps>
+
+1. **Run the changeset command**
+
+   ```bash
+   npm run changeset
+   ```
+
+2. **Select affected packages**
+
+   The CLI will either:
+   - Auto-detect changed packages by comparing with git
+   - Prompt you to manually select packages
+
+   ```
+   🦋  Which packages would you like to include?
+   ◯ @bluealba/pae-core-lib
+   ◉ @bluealba/pae-habits-service
+   ◯ @bluealba/pae-shell-ui
+   ```
+
+   Use arrow keys and space to select.
+
+3. **Choose version bump type**
+
+   For each selected package, choose:
+
+   - **Patch** (0.0.X): Bug fixes, minor changes, no breaking changes
+   - **Minor** (0.X.0): New features, backwards compatible
+   - **Major** (X.0.0): Breaking changes, incompatible API changes
+
+   ```
+   🦋  What kind of change is this for @bluealba/pae-habits-service?
+   ❯ patch
+     minor
+     major
+   ```
+
+   <Aside type="tip">
+     **Semantic Versioning**:
+     - **Patch**: Bug fixes, typos, performance improvements
+     - **Minor**: New features, new API methods, optional parameters
+     - **Major**: Removing APIs, changing signatures, breaking changes
+   </Aside>
+
+4. **Write a summary**
+
+   Describe your changes:
+
+   ```
+   🦋  Please enter a summary for this change:
+   Add user preferences API endpoints with CRUD operations
+   ```
+
+   This appears in the changelog.
+
+5. **Review and confirm**
+
+   The CLI shows a summary and creates files in `.changeset/`:
+
+   ```
+   🦋  Changeset created:
+   ✔ .changeset/brave-bears-jump.md
+   ```
+
+6. **Commit the changeset**
+
+   ```bash
+   git add .changeset/brave-bears-jump.md
+   git commit -m "Add changeset for user preferences feature"
+   ```
+
+</Steps>
+
+### Changeset File Format
+
+Changesets are markdown files:
+
+```markdown
+---
+"@bluealba/pae-habits-service": minor
+"@bluealba/pae-core-lib": patch
+---
+
+Add user preferences API endpoints with CRUD operations
+
+- Add GET /preferences endpoint
+- Add POST /preferences endpoint
+- Add PUT /preferences/:id endpoint
+- Add DELETE /preferences/:id endpoint
+- Update core-lib with preferences types
+```
+
+### Multiple Changesets
+
+You can create multiple changesets in one branch:
+
+```bash
+# Make some changes
+npm run changeset
+git add .changeset/
+git commit -m "Add changeset for feature A"
+
+# Make more changes
+npm run changeset
+git add .changeset/
+git commit -m "Add changeset for feature B"
+```
+
+The release process will merge them.
+
+---
+
+## Linting and Formatting
+
+Ensure code quality before committing:
+
+### Running Linters
+
+```bash
+# Lint everything
+npx turbo lint
+
+# Lint specific package
+npx turbo lint --filter=@bluealba/pae-habits-service
+
+# Auto-fix linting issues
+npx turbo lint:fix
+```
+
+### Format Code
+
+Most IDEs auto-format on save, but you can manually format:
+
+```bash
+# Using Prettier (if configured)
+npx prettier --write "src/**/*.ts"
+
+# Using ESLint
+npx eslint --fix "src/**/*.ts"
+```
+
+<Aside type="tip">
+  **IDE Setup**: Configure VS Code to auto-format on save:
+
+  ```json
+  {
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.fixAll.eslint": true
+    }
+  }
+  ```
+</Aside>
+
+---
+
+## Creating a Pull Request
+
+Once your feature is complete, tested, and you've created a changeset, create a PR.
+
+<Steps>
+
+1. **Push your branch**
+
+   ```bash
+   git push origin feature/add-user-preferences
+   ```
+
+   If this is the first push:
+
+   ```bash
+   git push -u origin feature/add-user-preferences
+   ```
+
+2. **Open GitHub**
+
+   Navigate to the repository on GitHub. You'll see a prompt to create a PR.
+
+3. **Fill out the PR template**
+
+   Provide a clear description:
+
+   ```markdown
+   ## Description
+   Add user preferences API endpoints to allow users to save and retrieve preferences.
+
+   ## Changes
+   - Add PreferencesService with CRUD operations
+   - Add PreferencesController with REST endpoints
+   - Add PreferencesDto for validation
+   - Add integration tests
+   - Update core-lib with Preferences entity
+
+   ## Testing
+   - Added unit tests for PreferencesService
+   - Added integration tests for API endpoints
+   - Tested manually via Postman
+   - All existing tests pass
+
+   ## Checklist
+   - [x] Tests added/updated
+   - [x] Documentation updated
+   - [x] Changeset created
+   - [x] Code builds successfully
+   - [x] Linter passes
+   ```
+
+4. **Set base branch to `develop`**
+
+   Ensure your PR targets `develop`, not `main`.
+
+5. **Request reviews**
+
+   Tag team members for review.
+
+6. **Address feedback**
+
+   Make changes based on review comments:
+
+   ```bash
+   # Make changes
+   git add .
+   git commit -m "Address PR feedback: add error handling"
+   git push
+   ```
+
+   The PR updates automatically.
+
+7. **Ensure CI passes**
+
+   Wait for CI checks to complete:
+   - Build check
+   - Test check
+   - Lint check
+   - Changeset check
+
+   Fix any failures before merging.
+
+</Steps>
+
+<Aside type="note">
+  **CI Checks**: All PRs must pass automated checks before merging. This includes builds, tests, lints, and changeset validation.
+</Aside>
+
+---
+
+## Working with Turborepo
+
+Turborepo is the build system that powers the monorepo.
+
+### Key Commands
+
+<Tabs>
+  <TabItem label="Build">
+    ```bash
+    # Build everything
+    npx turbo build
+
+    # Build specific package
+    npx turbo build --filter=@bluealba/pae-core-lib
+
+    # Build with dependencies
+    npx turbo build --filter=@bluealba/pae-habits-service...
+
+    # Force rebuild (bypass cache)
+    npx turbo build --force
+    ```
+  </TabItem>
+
+  <TabItem label="Test">
+    ```bash
+    # Test everything
+    npx turbo test
+
+    # Test specific package
+    npx turbo test --filter=@bluealba/pae-core-lib
+
+    # Test changed packages
+    npx turbo test --filter=...[origin/develop]
+    ```
+  </TabItem>
+
+  <TabItem label="Dev">
+    ```bash
+    # Run all apps in dev mode
+    npx turbo dev
+
+    # Run specific app
+    npx turbo dev --filter=@bluealba/pae-shell-ui
+
+    # Run multiple apps
+    npx turbo dev --filter=@bluealba/pae-shell-ui --filter=@bluealba/pae-admin-ui
+    ```
+  </TabItem>
+
+  <TabItem label="Clean">
+    ```bash
+    # Clean all build artifacts
+    npx turbo clean
+
+    # Clean specific package
+    npx turbo clean --filter=@bluealba/pae-core-lib
+    ```
+  </TabItem>
+</Tabs>
+
+### Understanding Filters
+
+Filters control which packages Turborepo operates on:
+
+```bash
+# Single package
+--filter=@bluealba/pae-core-lib
+
+# Package and its dependencies
+--filter=...@bluealba/pae-habits-service
+
+# Package and its dependents
+--filter=@bluealba/pae-core-lib...
+
+# Multiple packages
+--filter=@bluealba/pae-core-lib --filter=@bluealba/pae-habits-service
+
+# Changed packages since a branch
+--filter=...[origin/develop]
+
+# Glob patterns
+--filter="@bluealba/pae-*-service"
+```
+
+### Turborepo Caching
+
+Turborepo caches build outputs for speed:
+
+- **Cache hit**: Task skipped, output restored from cache
+- **Cache miss**: Task runs, output cached
+
+View cache information:
+
+```bash
+npx turbo build --summarize
+```
+
+Clear cache:
+
+```bash
+rm -rf node_modules/.cache/turbo
+```
+
+---
+
+## Common Workflows
+
+### Workflow 1: Adding a New Feature to a Service
+
+<Steps>
+
+1. Create feature branch from `develop`
+2. Make changes to the service code
+3. Add tests for new functionality
+4. Run tests locally: `npx turbo test --filter=@bluealba/pae-habits-service`
+5. Build: `npx turbo build --filter=@bluealba/pae-habits-service`
+6. Test manually by running service: `npm run dev`
+7. Create changeset: `npm run changeset`
+8. Commit changes including changeset
+9. Push and create PR
+
+</Steps>
+
+### Workflow 2: Updating a Shared Library
+
+<Steps>
+
+1. Create feature branch from `develop`
+2. Make changes to the library (e.g., `pae-core-lib`)
+3. Add tests for new functionality
+4. Build library: `npx turbo build --filter=@bluealba/pae-core-lib`
+5. Test dependent packages: `npx turbo test --filter=@bluealba/pae-core-lib...`
+6. Create changeset for library: `npm run changeset`
+7. Commit and push
+8. Create PR
+
+</Steps>
+
+<Aside>
+  **Dependency Impact**: When updating shared libraries, test all dependent packages. Turborepo makes this easy with the `...` filter syntax.
+</Aside>
+
+### Workflow 3: Fixing a Bug
+
+<Steps>
+
+1. Create fix branch from `develop`
+2. Write a failing test that reproduces the bug
+3. Fix the bug
+4. Verify test now passes
+5. Run full test suite: `npx turbo test`
+6. Create changeset (usually a patch): `npm run changeset`
+7. Commit and push
+8. Create PR with "fix:" prefix
+
+</Steps>
+
+### Workflow 4: Adding a New UI Component
+
+<Steps>
+
+1. Create feature branch from `develop`
+2. Add component to `pae-ui-react-core`
+3. Write component tests
+4. Add Storybook story (if applicable)
+5. Build: `npx turbo build --filter=@bluealba/pae-ui-react-core`
+6. Test in a UI app that uses the component
+7. Create changeset: `npm run changeset`
+8. Commit and push
+9. Create PR
+
+</Steps>
+
+---
+
+## Best Practices
+
+<CardGrid>
+  <Card title="Small, Focused PRs" icon="approve-check">
+    Keep PRs focused on one feature or fix. Easier to review and less likely to have conflicts.
+  </Card>
+
+  <Card title="Test Everything" icon="seti:test">
+    Write tests for new functionality and bug fixes. Maintain high test coverage.
+  </Card>
+
+  <Card title="Always Create Changesets" icon="document">
+    Never forget changesets. They're required for proper versioning and releases.
+  </Card>
+
+  <Card title="Keep Branches Updated" icon="rocket">
+    Regularly merge `develop` into your branch to avoid large merge conflicts.
+  </Card>
+
+  <Card title="Clear Commit Messages" icon="pencil">
+    Write descriptive commit messages. They become part of the project history.
+  </Card>
+
+  <Card title="Leverage Turborepo" icon="setting">
+    Use Turborepo filters to work efficiently with the monorepo.
+  </Card>
+</CardGrid>
+
+---
+
+## Release Process
+
+Releases are automated, but here's how they work:
+
+### Automatic Releases
+
+1. **Accumulation Phase**: Developers create changesets in PRs
+2. **Merge to Develop**: PRs are merged, changesets accumulate
+3. **Release Decision**: Team decides to cut a release
+4. **CI Creates RC**: Automated workflow creates release candidate branch
+5. **Version Bump**: CI uses changesets to bump versions
+6. **Changelog Generation**: CI generates changelog from changesets
+7. **Testing**: RC is deployed to staging for final testing
+8. **Merge to Main**: RC is merged to `main`
+9. **Publish**: Packages are published to npm (if public)
+10. **Deploy**: Production deployment is triggered
+
+### Manual Release (if needed)
+
+If you need to manually create a release:
+
+```bash
+# Generate version bumps from changesets
+npx changeset version
+
+# Review changes
+git diff
+
+# Commit version bumps
+git add .
+git commit -m "Version bump for release"
+
+# Tag release
+git tag v1.2.3
+
+# Push
+git push origin develop --tags
+```
+
+<Aside type="caution">
+  **Caution**: Manual releases are rarely needed. The automated process is preferred for consistency and reliability.
+</Aside>
+
+---
+
+## Next Steps
+
+You now understand the complete development workflow!
+
+Explore these topics next:
+
+1. **[Core Concepts](/_/docs/getting-started/core-concepts/)** - Deeper understanding of platform concepts
+2. **[Architecture](/_/docs/architecture/overview/)** - Learn the technical architecture
+3. **[Building Services](/_/docs/guides/building-services/)** - Create your first service
+4. **[Building UIs](/_/docs/guides/building-uis/)** - Create your first micro-frontend
+
+## Getting Help
+
+If you encounter workflow issues:
+
+1. **Check CI logs**: Review failed checks on GitHub
+2. **Ask the team**: Slack or GitHub Discussions
+3. **Review this guide**: The answer might be here
+4. **Check Turborepo docs**: [turbo.build](https://turbo.build/)
+5. **Check Changesets docs**: [changesets](https://github.com/changesets/changesets)
+
+Happy coding!