DIRACGrid · aldbr · Sep 2, 2025
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -14,4 +14,4 @@ Thank you for your interest in contributing to our project! We appreciate all co
   - Create a [:bust_in_silhouette: User Story](https://github.com/DIRACGrid/diracx-web/discussions/categories/user-personas-and-stories) to describe your need and share your design ideas if any.
 
 - **Want to contribute to the :computer: codebase?**
-  - Read the [:book: Developer Guide](docs/developer/index.md) to set up your environment and get started.
+  - Read the [:book: Developer Guide](docs/dev/how-to/contribute.md) to set up your environment and get started.
diff --git a/docs/admin/deploy_instance.md b/docs/admin/deploy_instance.md
diff --git a/docs/admin/how-to/deploy_instance.md b/docs/admin/how-to/deploy_instance.md
@@ -0,0 +1,56 @@
+# Deploying the web interface
+## DiracX-Web
+
+### Development mode
+
+Refer to the [Developer Guide: Getting Started](../../dev/tutorials/getting_started.md) for instructions on running `diracx-web` in development mode.
+
+### Production mode
+
+To deploy `diracx-web` in a production environment, you need to customize the [`diracx` Helm Chart](https://github.com/DIRACGrid/diracx-charts) values. Key parameters include:
+
+```yaml title="Helm Chart values for production deployment"
+global.images.web.tag: <latest diracx-web version, docker tag>
+global.images.web.repository: <diracx-web docker image>
+```
+
+!!! tip "Version Configuration"
+    Make sure to update these values to point to the appropriate Docker image and version for your deployment.
+
+### Integrating new features/hotfixes
+
+=== "Testing Features"
+
+    To hotfix `diracx-web` or test new features, you can provide a specific PR within [`diracx` Helm Chart](https://github.com/DIRACGrid/diracx-charts) values, such as:
+
+    ```yaml title="Helm Chart values for feature testing"
+    diracxWeb.repoURL: <repository hosting the branch you want to apply>
+    diracxWeb.branch: <branch hosting the changes you want to apply>
+    ```
+
+=== "Production Hotfixes"
+
+    For urgent production hotfixes:
+
+    1. Create a hotfix branch from the production release
+    2. Apply the minimal fix required  
+    3. Test thoroughly in a staging environment
+    4. Update the Helm Chart values to point to the hotfix image
+
+!!! warning "Deployment Safety"
+    Always test changes in a staging environment before applying to production.
+
+## Extension
+
+
+### `gubbins` extension in development mode
+
+For managing the `gubbins` extension in development mode, refer to the [Developer Guide: Managing an extension](../../dev/how-to/manage_extension.md).
+
+### `gubbins` extension in development mode, as a standalone
+
+By default, the `gubbins` extension is part of a monorepo and uses a local version of `diracx-web-components`. This setup is not representative of a standalone extension configuration.
+
+To deploy gubbins as a standalone package:
+- **Isolate the `packages/extensions` directory:** Copy the content of `packages/extensions` to a new repository or directory outside the monorepo.
+- **Update Configuration:** Adjust relevant variables to align with a standalone setup. Review the gubbins-test GitHub Action workflow for required changes.
diff --git a/docs/admin/how-to/index.md b/docs/admin/how-to/index.md
@@ -0,0 +1,32 @@
+# Administrator How-To Guides
+
+This section provides guides for administrators managing DiracX Web deployments and infrastructure.
+
+## Available Guides
+
+!!! info "Deployment Guide"
+    Start with the [Deployment Guide](../deploy_instance.md) for setting up DiracX Web in production.
+
+=== "Deployment & Operations"
+
+    **[Deploy Instance](../deploy_instance.md)**
+    : Complete guide for deploying DiracX Web in production environments.
+
+=== "Maintenance"
+
+    **[Manage Dependencies](../manage_dependencies.md)**  
+    : Learn how to handle dependency updates and security vulnerabilities.
+
+    **[Manage Releases](../manage_release.md)**
+    : Guide for managing DiracX Web releases and versioning.
+
+## Best Practices
+
+!!! tip "Production Checklist"
+    - Always test in staging before deploying to production
+    - Monitor application performance and logs
+    - Keep dependencies updated for security
+    - Maintain proper backup procedures
+
+!!! warning "Security Considerations"
+    Regularly review and apply security updates. Enable automated security alerts in your GitHub repository settings.
diff --git a/docs/admin/how-to/manage_dependencies.md b/docs/admin/how-to/manage_dependencies.md
@@ -0,0 +1,73 @@
+# Managing web dependencies
+
+## Updating dependencies
+
+[Dependabot](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates) is a GitHub-integrated tool that automates dependency management by regularly checking for updates and creating pull requests (PRs) to keep your project's dependencies current. 
+
+!!! info "Weekly Schedule"
+    In the `diracx-web` repository, Dependabot is configured to run weekly, generating PRs for any outdated or vulnerable dependencies.
+
+=== "Review PRs"
+
+    **Access PRs**
+    : Navigate to the repository's "Pull Requests" section to view Dependabot's submissions.
+
+    **Examine Changes** 
+    : Assess the proposed updates, paying close attention to any major version changes that might introduce breaking changes.
+
+=== "Verify Tests"
+
+    **Automated Tests**
+    : Ensure that all continuous integration (CI) checks and automated tests pass successfully for each Dependabot PR.
+
+    **Handle Failures**
+    : If tests fail, investigate the cause by reviewing the dependency's changelog or release notes to identify any breaking changes or incompatibilities.
+
+=== "Adapt Code"
+
+    **Local Development**
+    : ```bash title="Working with Dependabot branches"
+      # Check out the PR branch locally
+      git checkout dependabot/branch-name
+
+      # Run tests locally
+      npm test
+
+      # Make necessary fixes
+      # ... edit code ...
+
+      # Test your changes
+      npm run test:diracx-web-components
+      npm run --prefix packages/diracx-web test
+      ```
+
+    **Implement Fixes**
+    : Modify the codebase to address any issues introduced by the dependency update.
+
+=== "Merge & Monitor"
+
+    **Final Review**
+    : Once tests pass and the codebase is stable, proceed to merge the PR into the main branch.
+
+    **Post-Merge Actions**
+    : Monitor the application post-deployment to ensure that the update does not introduce any unforeseen issues.
+
+    !!! warning "Deployment Monitoring"
+        Keep a close eye on the application after dependency updates to catch any unexpected issues early.
+
+## Managing Security Vulnerabilities
+
+Dependabot also helps in identifying and addressing security vulnerabilities in your project's dependencies. When a vulnerability is detected, Dependabot generates alerts and can automatically create PRs to update the affected dependencies.
+
+!!! danger "Security Alert Process"
+    Navigate to the repository's **"Security"** tab and select **"Dependabot alerts"** to view any security vulnerabilities identified in the dependencies.
+
+    **Priority Levels:**
+
+    - **Critical**: Immediate action required
+    - **High**: Address within 1 week  
+    - **Medium**: Address within 1 month
+    - **Low**: Address during next maintenance cycle
+
+!!! tip "Proactive Security"
+    Enable GitHub's security alerts and automatic security updates for immediate notification of vulnerabilities in your dependencies.
diff --git a/docs/admin/manage_release.md → docs/admin/how-to/manage_release.md b/docs/admin/manage_release.md → docs/admin/how-to/manage_release.md
@@ -1,4 +1,4 @@
-# Release Management
+# Managing web releases
 
 ```mermaid
 sequenceDiagram

diff --git a/docs/admin/manage_dependencies.md b/docs/admin/manage_dependencies.md
diff --git a/docs/dev/web-arch.md → docs/dev/explanations/web-arch.md b/docs/dev/web-arch.md → docs/dev/explanations/web-arch.md
@@ -1,10 +1,4 @@
-
-# Developer Guide
-
-Welcome to the DiracX-Web Developer Guide! This guide will help you navigate and ramp you up. Adding features, fixing the code in a consistent manner with tests and documentation will become a second nature.
-
-
-## Architecture Overview
+# Web architecture Overview
 
 ```mermaid
 ---
@@ -38,17 +32,23 @@ flowchart TD
 
 This repository is organized as a monorepo, with the following key packages:
 
-- [**DiracX-Web-Components**](packages/diracx-web-components): A library of reusable React components designed for integration within the `DiracX-Web` package and to facilitate the creation of custom DiracX web extensions.
+=== "DiracX-Web-Components"
 
-- [**DiracX-Web**](packages/diracx-web): Vanilla Dirac web interface based on Next.js. Leverages components from `DiracX-Web-Components` to provide core functionalities.
+    **Purpose**: A library of reusable React components  
+    **Location**: `packages/diracx-web-components`  
+    **Description**: Designed for integration within the `DiracX-Web` package and to facilitate the creation of custom DiracX web extensions.
 
-- [**Extensions**](packages/extensions): An illustrative example of a web extension, also based on Next.js, demonstrating how to extend the functionality of `DiracX-Web` using the components from the `DiracX-Web-Components` package.
+=== "DiracX-Web" 
 
+    **Purpose**: Main web application  
+    **Location**: `packages/diracx-web`  
+    **Description**: Vanilla Dirac web interface based on Next.js. Leverages components from `DiracX-Web-Components` to provide core functionalities.
 
-The monorepo structure is based on *npm workspaces* to ensure that related packages ([DiracX-Web-Components](packages/diracx-web-components)) are automatically used from their local versions instead of fetching them from the npm registry.
+=== "Extensions"
 
-## Ramping up
+    **Purpose**: Example extension implementation  
+    **Location**: `packages/extensions`  
+    **Description**: An illustrative example of a web extension, also based on Next.js, demonstrating how to extend the functionality of `DiracX-Web` using the components from the `DiracX-Web-Components` package.
 
-- [Set up a development environment](setup_environment.md)
-- [Manage the extension](manage_extension.md)
-- [Contribute to the effort](../developer/contribute.md)
+!!! info "Monorepo Structure"
+    The monorepo structure is based on *npm workspaces* to ensure that related packages ([DiracX-Web-Components](packages/diracx-web-components)) are automatically used from their local versions instead of fetching them from the npm registry.
diff --git a/docs/dev/how-to/contribute.md b/docs/dev/how-to/contribute.md
@@ -0,0 +1,82 @@
+# Contributing to DiracX-Web
+
+### 1. Open an Issue
+
+!!! tip "Discussion First"
+    Before making a pull request (PR), especially for non-trivial changes, please [open an issue](https://github.com/DIRACGrid/diracx-web/issues) to discuss your idea. This ensures that everyone is aligned on the proposed change.
+
+!!! info "Check Existing Issues"
+    Before opening a new issue, please check if a similar issue already exists. If a similar issue exists, consider contributing to the discussion there instead.
+
+!!! success "Good First Issues"
+    If you want to start contributing right away, check out the issues labeled with ["good first issue"](https://github.com/DIRACGrid/diracx-web/labels/good%20first%20issue). These are issues that are well-suited for newcomers to the project.
+
+### 2. Make Changes
+
+!!! info "Requirements"
+    [Getting Started](../tutorials/getting_started.md)
+
+=== "Repository Setup"
+
+    **Fork the Repository**
+    : Start by forking the repository and creating a new branch for your work. Use a descriptive name for your branch that reflects the work you are doing.
+
+=== "Documentation"
+
+    **Code Documentation**
+    : Ensure that any code you write is well-documented. This includes:
+
+    - Inline comments where necessary to explain complex logic
+    - Updating or creating Storybook documentation if you are contributing to the `diracx-web-components` library
+    - You can use tools like [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) to maintain code quality
+
+=== "Testing"
+
+    **Component Testing**
+    : Write tests for your stories to ensure they work as expected. Use [Jest](https://jestjs.io/) for unit testing and snapshot testing of your React components.
+
+    **Application Testing**
+    : Use [Cypress](https://www.cypress.io/) for end-to-end testing to simulate real user interactions and ensure your application behaves correctly.
+
+    **Test Coverage**
+    : Maintain good test coverage to ensure that your critical features are well-protected during updates. Tools like Jest provide [coverage reports](https://jestjs.io/docs/code-coverage) that help you identify untested parts of your code.
+
+=== "Accessibility"
+
+    **Inclusive Design**
+    : Make your application accessible to all users. Use semantic HTML, ARIA attributes, and test your application with different screen sizes and assistive technologies.
+
+!!! tip "Component Exports"
+    If you create an export function or component in `diracx-web-components`, you must add it to the `index.ts` file and run `npm run build` inside `packages/diracx-web-components` to ensure the pre-commit hook passes.
+
+!!! warning "Breaking Changes"
+    Don't forget to update the `packages/extensions` code if you integrate breaking changes in the `diracx-web-components` library. See [Managing the extension](manage_extension.md) for further details. 
+
+### 3. Commit
+
+!!! info "Conventional Commits Required"
+    All commits must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. This ensures that commit messages are structured and consistent, which is important for automation and versioning.
+
+**Examples:**
+```
+feat(ui): add new button component
+fix(api): handle null values in response
+docs(readme): update contributing guidelines
+```
+
+!!! danger "CI Requirement"
+    If your commit messages do not follow this convention, the Continuous Integration (CI) process will fail, and your PR will not be merged. Please ensure your commit messages are properly formatted before pushing.
+
+!!! note "Pre-commit Hooks"
+    `Husky` is configured to run as a pre-commit script, executing tasks such as linting staged files to maintain code consistency with the codebase.
+
+
+### 4. Make a Pull Request (PR)
+
+- **Submit Your PR:** When you’re ready, submit your pull request. Please include a clear description of what your PR does and reference the issue number it addresses (if applicable).
+- **Review Process:** Your PR will be reviewed by project maintainers. Please be patient and responsive to any feedback you receive.
+
+### 5. Additional Notes
+
+- **Trivial Changes:** For minor changes like fixing typos, feel free to skip the issue creation step and go straight to making a PR.
+- **Stay Up-to-Date:** Make sure your branch is up-to-date with the latest changes in the main branch before submitting your PR. Use `git rebase` if necessary.