Overcoming Barriers for New Contributors

This document addresses documentation gaps and provides clear setup instructions, environment details, and architectural overviews to help new contributors onboard effectively.

# Govtool repository
Barriers are described in the folder structure below

## docs

**Issue**: Project architecture and fees documentation are outdated (last update: 2024-06-06).
https://github.com/IntersectMBO/govtool/blob/develop/docs/architecture/Architecture%20diagram.png

**Resolution**:
- The project architecture and fees have been updated to reflect the latest structure as of current date.

### Action for Contributors:
Review these documents to understand the system's design and cost model.

## govtool

**Issues**:
- Missing README.md.

**Resolution**:
- Created a detailed README.md with directory structure and navigation.
- Linked key documentation for architecture, operations, and governance actions from /docs for better onboarding.

## govtool/analytics-dashboard

**Issues**:
- Missing environment setup details in README.md.
- Lack of guides explaining how the dashboard works

**Resolution**:
- Added environment setup instructions with example .env.
- Included a guide on how the dashboard functions.

## govtool/backend

**Issues**:
- Missing PostgreSQL version requirement (>= 14.12).
- Invalid [docker-compose link](https://github.com/IntersectMBO/govtool/blob/develop/scripts/govtool/docker-compose.node+dbsync.yml) in README.md
- Missing command to enter the Nix environment
- Missing ghcup setup link instruction.

**Resolution**:
- Updated README with PostgreSQL version and fixed docker-compose link ,included ghcup setup link and command to enter nix environment before ghcup install

## govtool/frontend

**Issues**:
- Missing environment setup details for pillars API keys and metadata API URL.
- Unable to load outcome/proposal pillar details due to missing environment examples.
- Missing outcome and proposal pillar architecture, how it was implemented details in README.md.
- As Outcome and Proposal Pillars are microservices, new contributors are unaware of their structure. For fixing issues or adding features, contributors may not know about the separate repositories for these pillars.

**Resolution**:
- Added environment setup with example `.env`.
- Provided architecture, include seperate repository links and implementation details for outcome and proposal pillars.

## govtool/metadata-validation
**Issues**:
- Missing instruction to fill `.env` based on `.env.example`.
- Missing validation guide and architecture details.

**Resolution**:
- Added `.env` setup instruction.
- Created a validation guide with architecture overview.

## gov-action-loader

**Issue**:
- Missing README.md

**Resolution**:
- Added README with directory structure and navigation.

# GovTool Proposal Pillars Repository

### 1. README Typo
**Location**: `govtool-proposal-pillars` repository README
**Issue**: The README contains a typo:
- Current: "This is the repository which holds GovTool's Voting Pillar packages."
- Expected: "This is the repository which holds GovTool's Proposal Pillar packages."
**Suggestion**: Correct the typo in the README to accurately reflect the repository's purpose.

### 2. Backend Issues
**Location**: `backend` package
**Issues**:
1. **Missing `.env.example`**: No `.env.example` file is provided, leaving contributors without guidance on required environment variables.
2. **Backend Fails to Start**: The backend fails to initialize, halting at a "Loading Strapi" error with the message: "No SQLite package found." This prevents further development or testing of backend flows.

**Suggestions**:
- Include a `.env.example` file listing all required environment variables and their expected format.
- Resolve the missing SQLite package dependency issue. Update the `backend` README with:
- Clear setup instructions, including dependency installation (e.g., SQLite).
- Steps to verify a successful backend startup.

### 3. PDF-UI Documentation
**Location**: `pdf-ui` package
**Issue**: The README lacks critical setup and build instructions, hindering contributors from running the frontend locally or contributing fixes/features. It only provides usage details for the published package. The absence of a `.env.example` and local setup steps prevents any progress.

**Suggestions**:
- Add a `.env.example` file for the `pdf-ui` , if applicable, with necessary environment variables.
- Update the README with a detailed section including:
- Prerequisites (e.g., Node.js version, dependencies).
- Step-by-step instructions for running the package locally.
- Steps for building and publishing updates or fixes.

### 4. Version Tagging for Proposal Pillars
**Issues**:
Currently, there is no version tag for the Proposal Pillars package, making it difficult for new contributors and package users to identify the current version or track updates.

**Suggestions**
To improve clarity and accessibility, we recommend implementing proper version tagging. Each tag should include a clear message detailing fixes and features introduced in that version. This will allow contributors and users to easily understand the current package version and the specific updates or enhancements included in each release.

# govtool-outcome-pillars repository
https://github.com/IntersectMBO/govtool-outcomes-pillar/issues/3