IntersectMBO · kusssal · Sep 8, 2026 · Sep 11, 2026
@@ -1,16 +1,8 @@
 # Contributing to the `GovTool` project
 
-⚠️ This is a work in progress document, more instruction on how-to contribute to come!
-
-Contributing todo:
-
-- [ ] Align with latest OSC policies
-- [ ] Refactor to reflect reality
-- [ ] Make more friendly to open source contributors
-
 Thanks for considering contributing and helping us on creating GovTool! 😎
 
-The best way to contribute right now is to try things out and provide feedback, but we also accept contributions to the documentation and the obviously to the code itself.
+We welcome bug reports, documentation improvements, and code contributions. Contributors should work from a focused branch based on `develop` and open a pull request targeting `develop`.
 
 This document contains guidelines to help you get started and how to make sure your contribution gets accepted, making you our newest GovTool contributor!
 
@@ -30,7 +22,7 @@ This document contains guidelines to help you get started and how to make sure y
     - [Branch Naming](#branch-naming)
     - [Commit Messages](#commit-messages)
       - [Rationale](#rationale)
-    - [Merge Commit PRs and Rebase Branches on top of Main](#merge-commit-prs-and-rebase-branches-on-top-of-main)
+    - [Merge PRs and Rebase Branches on top of develop](#merge-prs-and-rebase-branches-on-top-of-develop)
       - [Rationale](#rationale-1)
     - [Versioning](#versioning)
     - [Changelog](#changelog)
@@ -112,8 +104,8 @@ Welcome to contributing to `GovTool`! Whether you're fixing a bug, adding a feat
 #### Getting Started
 
 1. **Set Up Your Environment**:
-   - Follow the instructions in [`README.md`](./README.md) file and navigate to the specific folder corresponding to the form you want to fix or enhance.
-   - Follow the setup instructions to clone the repository and install the necessary dependencies.
+   - Follow the [local development instructions](./README.md#-local-development) to clone the repository, select the required Node.js version, create the environment file, install dependencies, and start the frontend.
+   - For another component, use its setup guide: [frontend](./govtool/frontend/README.md), [backend](./govtool/backend/README.md), or [Docker Compose](./docker/README.md).
    - Make sure you're using the latest version of the project to avoid potential conflicts.
 
 2. **Find an Issue to Work On**:
@@ -131,19 +123,19 @@ Welcome to contributing to `GovTool`! Whether you're fixing a bug, adding a feat
     - Fork the `govtool` repository on GitHub to create a copy under your account.
 
 
-4. **Create a Branch**:
+5. **Create a Branch**:
    - Create a new branch from the `develop` branch with a descriptive name (see [Branch Naming](#branch-naming)).
    - Example: `feat/123-add-voting-ui` or `fix/456-update-api-endpoint`.
 
-5. **Make Your Changes**:
+6. **Make Your Changes**:
    - Write clean, well-documented code following the [Style Guides](#style-guides) for React, Haskell, CSS, or other relevant technologies.
    - Add or update tests to ensure your changes are robust.
    - Keep your changes focused and aligned with the issue’s scope.
 
-6. **Commit Your Changes**:
+7. **Commit Your Changes**:
    - Write clear, concise commit messages following the [Commit Messages](#commit-messages) guidelines.
 
-7. **Submit a Pull Request**:
+8. **Submit a Pull Request**:
 
    `If You Have Push Permissions to the Original Repository`
     - Push your branch to the repository and create a pull request (PR) to the `develop` branch.
@@ -155,12 +147,12 @@ Welcome to contributing to `GovTool`! Whether you're fixing a bug, adding a feat
    - Describe your changes clearly, including why they’re needed and how they were tested.
    - If your PR isn’t ready for review, mark it as a draft.
 
-8. **Address Feedback**:
+9. **Address Feedback**:
    - Expect reviews from maintainers or other contributors (see [CODEOWNERS](./CODEOWNERS)).
    - Respond to feedback promptly and make requested changes.
    - Once approved, your PR will be merged into `develop` by the author after passing tests.
 
-9. **Celebrate Your Contribution!**:
+10. **Celebrate Your Contribution!**:
     - Once merged, your changes will move through the [Development Processes](#development-processes) (QA, staging, etc.).
     - You’re now a `GovTool` contributor! Share your achievement and consider tackling another issue.
 
@@ -224,12 +216,12 @@ There is plenty to say on this topic, but broadly the guidelines in [this post](
 Git commit messages are our only source of why something was changed the way it was changed.
 So we better make the readable, concise and detailed (when required).
 
-### Merge Commit PRs and Rebase Branches on top of Main
+### Merge PRs and Rebase Branches on top of `develop`
 
 When closing branches / PRs use merge commits, so we have a history of PRs also in the git history.
-Do not merge main into side branches, instead rebase them on top of main.
-Try to keep branches up-to-date with main (not strict requirement though).
-Once merged to main, please delete the branch.
+Do not merge `develop` into side branches; instead, rebase them on top of `develop`.
+Try to keep branches up-to-date with `develop` (not a strict requirement).
+Once merged into `develop`, please delete the branch.
 
 **Tip:** Use Github's merge button in PRs to merge with commit.
 This strategy helps us operate on the commits you've delivered: it's easier to [cherry-pick a merge commit](https://git-scm.com/docs/git-cherry-pick#Documentation/git-cherry-pick.txt--mltparent-numbergt) than a series of commits, and it's also easier to [revert changes using a merge commit](https://git-scm.com/docs/git-revert#Documentation/git-revert.txt--mparent-number) instead of a series of reverts.

@@ -1,15 +1,104 @@
-# Security Policy
+# Security Vulnerability Disclosure Policy
 
-## Reporting a Vulnerability
+## Introduction
 
-Please report (suspected) security vulnerabilities to [security@intersectmbo.org](security@intersectmbo.org).
-You will receive a response from us within 48 hours.
-If the issue is confirmed, we will release a patch as soon as possible.
+The Cardano GovTool is committed to ensuring the security of
+its software and the privacy of its users. We value the contributions
+of the security community in helping us identify and address
+vulnerabilities in our code. This Security Vulnerability Disclosure
+Policy outlines how security vulnerabilities should be reported and
+how we will respond to and remediate such reports.
 
-Please provide a clear and concise description of the vulnerability, including:
+## Security Vulnerability Handling Process
 
-* the affected component(s) and version(s),
-* steps that can be followed to exercise the vulnerability,
-* any workarounds or mitigations
+### Reporting a Vulnerability
 
-If you have developed any code or utilities that can help demonstrate the suspected vulnerability, please mention them in your email but ***DO NOT*** attempt to include them as attachments as this may cause your Email to be blocked by spam filters.
+If you discover a security vulnerability in GovTool, we encourage you to
+responsibly disclose it to us. To report a vulnerability, please use
+the [security advisory form on GitHub](https://github.com/IntersectMBO/govtool/security/advisories/new)
+to draft a new _Security advisory_.
+
+Please include as many details as needed to clearly qualify the issue:
+
+- A description of the vulnerability and its potential impact.
+- Steps to reproduce the vulnerability.
+- The version of GovTool where the vulnerability exists.
+- Any relevant proof-of-concept or exploit code (if applicable).
+
+### Processing Vulnerability
+
+1. **Acknowledgment**: The team acknowledges the receipt of your report
+   within 3 business days by commenting on the issue reporting it or replying to email.
+
+2. **Validation**: The team investigates the issue and either _reject_ or _validate_ the
+   reported vulnerability.
+
+   a. **Rejection**: If the team rejects the report, detailed explanations will be provided by email or commenting on the relevant issue and the latter will be made public and closed as `Won't fix`.
+
+   b. **Acceptance**: If the team accepts the report, a CVE identifier will be requested through GitHub and a [private fork](https://docs.github.com/en/code-security/security-advisories/working-with-repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability) opened to work on a fix to the issue
+
+3. **Resolution**: The team works to resolve the vulnerability in a
+   timely manner. The timeline for resolution will depend on the
+   complexity and severity of the vulnerability, but we will strive to
+   address critical vulnerabilities as quickly as possible.
+
+4. **Collaboration**: While working on a fix, the team maintains open and transparent
+   communication with the reporter throughout the process, providing
+   updates on the status of the vulnerability and any steps taken to
+   remediate it. In particular this means that the reporter will be asked to review any proposed fix and to advise on the timing for public disclosure.
+
+5. **Fixing Issue**: The team agrees on the fix, the announcement, and the release schedule with the reporter. If the reporter is not responsive in a reasonable time frame this should not block the team from moving to the next steps particularly in the face of a high impact or high severity issue.
+
+   a. **Mitigation**: Depending on the severity and criticality of the issue, the team can decide to disclose the issue publicly in the absence of a fix _if and only if_ a clear, simple, and effective mitigation plan is defined. This _must_ include instructions for users and operators of the software, and a time horizon at which the issue will be properly fixed (eg. version number).
+
+   b. **Fix**: When a fix is available and approved, it should be merged and made available as quickly as possible:
+   - All commits to the private repository are squashed into a single commit whose description _should not_ make any reference that it relates to a security vulnerability
+   - A new Pull Request is created with this single commit
+   - This PR's review and merging is expedited as all the work as already been done
+
+6. **Release**: The team creates and publish a release that includes the fix
+
+7. **Announcement**: Concomitant to the release announcement, the team announces the security vulnerability by making the GitHub issue public. This is the first point that any information regarding the vulnerability is made public.
+
+   a. **Credit**: The team publicly acknowledges the contributions of the
+   reporter once the vulnerability is resolved, subject to the
+   reporter's preferences for attribution.
+
+8. **Disagreements**: In case of disagreements with the reporter on the fix, mitigation, timing, or announcement, the team has the final say.
+
+## Responsible Disclosure
+
+We kindly request that reporters adhere to responsible disclosure
+practices, which include:
+
+- **Do not disclose the vulnerability publicly**: Please refrain from
+  posting details of the vulnerability on public forums or social
+  media until it has been resolved.
+- **Do not exploit the vulnerability**: Do not attempt to exploit the
+  vulnerability to cause harm or gain unauthorized access to systems.
+- **Work with us**: Allow us a reasonable amount of time to
+  investigate and address the vulnerability before publicly disclosing
+  any details.
+
+## Legal Protections
+
+We will not pursue legal action against individuals who
+report security vulnerabilities to us.
+
+## Contact Information
+
+To report a security vulnerability, please use the [security advisory form on GitHub](https://github.com/IntersectMBO/govtool/security/advisories/new). Should you experience any issues reporting via GitHub or have other questions, please contact [security@intersectmbo.org](mailto:security@intersectmbo.org).
+
+## Revision of Policy
+
+This Security Vulnerability Disclosure Policy may be updated or
+revised as necessary. Please check the latest version of this policy
+on the [Open-Source-Office repository](https://github.com/IntersectMBO/Open-Source-Office/tree/add-security-policies/security-policy-documents).
+
+## Conclusion
+
+The GovTool project greatly appreciates the assistance of the security
+community in helping us maintain the security of our software while
+upholding the highest standards of privacy. Together, we can work to
+identify and address vulnerabilities, ensuring a safer and more secure
+experience for all users.
@@ -3,18 +3,5 @@ DBSYNC_POSTGRES_PORT=
 DBSYNC_POSTGRES_USER=
 DBSYNC_POSTGRES_PASSWORD=
 DBSYNC_DATABASE=
-APP_ENV="development"
-BASE_URL="http://localhost:9999"
-METADATA_API_URL="http://localhost:3000"
-NETWORK_FLAG=0
-SENTRY_DSN=""
-GTM_ID=""
-IS_DEV=true
-CHATWOOT_URL=""
-CHATWOOT_WEBSITE_TOKEN=""
-IS_PROPOSAL_DISCUSSION_FORUM_ENABLED='false'
-IS_GOVERNANCE_OUTCOMES_PILLAR_ENABLED='true'
 PDF_API_URL=""
-OUTCOMES_API_URL="http://localhost:3001/"
 IPFS_GATEWAY="https://ipfs.io/ipfs"
-IPFS_PROJECT_ID=""
@@ -16,7 +16,16 @@ cp .env.example .env
 > [!NOTE]
 > Update the backend config file used by the `govtool-backend` service in [`example-config.json`](../govtool/backend/example-config.json) before starting the stack.
 
-Also fill in the db-sync details and required URLs in the outcomes env file. Create env files for the frontend and metadata-validation services from their examples if they are not already present.
+Also create the frontend and metadata-validation environment files:
+
+```bash
+cp ../govtool/frontend/.env.example ../govtool/frontend/.env
+cp ../govtool/metadata-validation/.env.example ../govtool/metadata-validation/.env
+```
+
+Docker Compose loads the frontend container's runtime configuration from `govtool/frontend/.env`. Edit that file to configure the backend and metadata-validation URLs, network, and optional frontend integrations.
+
+Fill in the db-sync details and required service URLs in `docker/.env`.
 
 Note: The `.env.example` in this folder is for the outcomes service only.
 
@@ -29,6 +38,12 @@ Edit `docker/.env` with real values:
 - IPFS_GATEWAY
 - PDF_API_URL
 
+Validate the resolved Compose configuration before starting services:
+
+```bash
+docker compose config
+```
+
 ## Start services
 
 Option A: build locally (uses Dockerfiles)
@@ -47,4 +62,3 @@ docker compose up -d --no-build
 - Backend API: http://localhost:9999
 - Metadata validation: http://localhost:3000
 - Outcomes API: http://localhost:3001
-
@@ -46,26 +46,13 @@ services:
             context: ../govtool/frontend
             dockerfile: Dockerfile
         env_file:
-            - ./.envs
+            - ../govtool/frontend/.env
         environment:
-            VITE_BASE_URL: ${BASE_URL}
-            VITE_SENTRY_DSN: ${SENTRY_DSN_FRONTEND:-}
-            VITE_APP_ENV: ${APP_ENV:-test}
-            VITE_NETWORK_FLAG: ${VITE_NETWORK_FLAG:-0}
-            VITE_CHATWOOT_URL: ${CHATWOOT_URL:-}
-            VITE_CHATWOOT_WEBSITE_TOKEN: ${CHATWOOT_WEBSITE_TOKEN:-}
-            VITE_IS_PROPOSAL_DISCUSSION_FORUM_ENABLED: 'true'
-            VITE_METADATA_API_URL: ${METADATA_API_URL}
             UMAMI_URL: ${UMAMI_URL:-}
             UMAMI_WEBSITE_ID: ${UMAMI_WEBSITE_ID:-}
             UMAMI_SSL_VERIFY: ${UMAMI_SSL_VERIFY:-true}
             TRUSTED_PROXY_CIDRS: ${TRUSTED_PROXY_CIDRS:-}
             REAL_IP_HEADER: ${REAL_IP_HEADER:-X-Forwarded-For}
-            VITE_PDF_API_URL: ${PDF_API_URL:-}
-            VITE_OUTCOMES_API_URL: ${OUTCOMES_API_URL:-}
-            VITE_IPFS_GATEWAY: ${IPFS_GATEWAY:-https://ipfs.io/ipfs}
-            VITE_IPFS_PROJECT_ID: ${IPFS_PROJECT_ID:-}
-            VITE_IS_GOVERNANCE_OUTCOMES_PILLAR_ENABLED: 'true'
         ports:
             - "80:80"
         depends_on:

diff --git a/govtool/frontend/.env.example b/govtool/frontend/.env.example
@@ -1,15 +1,14 @@
 VITE_APP_ENV="development"
-VITE_BASE_URL=""
-VITE_METADATA_API_URL=""
+VITE_BASE_URL="http://localhost:9999"
+VITE_METADATA_API_URL="http://localhost:3000"
 VITE_NETWORK_FLAG=0
 VITE_SENTRY_DSN=""
-VITE_GTM_ID=""
 VITE_IS_DEV=true
 VITE_CHATWOOT_URL=""
 VITE_CHATWOOT_WEBSITE_TOKEN=""
-VITE_IS_PROPOSAL_DISCUSSION_FORUM_ENABLED='true'
-VITE_IS_GOVERNANCE_OUTCOMES_PILLAR_ENABLED='true'
+VITE_IS_PROPOSAL_DISCUSSION_FORUM_ENABLED='false'
+VITE_IS_GOVERNANCE_OUTCOMES_PILLAR_ENABLED='false'
 VITE_PDF_API_URL=""
 VITE_OUTCOMES_API_URL=""
-VITE_IPFS_GATEWAY=""
-VITE_IPFS_PROJECT_ID=""
+VITE_IPFS_GATEWAY="https://ipfs.io/ipfs"
+VITE_IPFS_PROJECT_ID=""