From cac618eac7f4b272e9c0a9fef7829639ef4ea73e Mon Sep 17 00:00:00 2001 From: icedmist Date: Tue, 13 Oct 2026 15:44:18 +0100 Subject: [PATCH] docs(contributing): formalize 5-step contribution workflow and update domain status --- CONTRIBUTING.md | 140 +++++++++++++++++++++++++++--------------------- README.md | 26 +++++++-- docs/PRD.md | 15 +++--- 3 files changed, 107 insertions(+), 74 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 176cbcf..3d15adf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,20 +73,22 @@ Install the versions supported by the repository and have access to: ### Get the code -Fork the repository on GitHub, then clone your fork: +Fork the repository on GitHub ([`geekinks/problemspot`](https://github.com/geekinks/problemspot)), then clone your personal fork: ```bash -git clone https://github.com/geekinks/problemspot.git +git clone https://github.com//problemspot.git cd problemspot ``` -Add the original repository as `upstream` if you have forked it: +Configure the upstream remote pointing to the main organization repository: ```bash git remote add upstream https://github.com/geekinks/problemspot.git ``` -Replace the placeholder organization and username with the actual repository details. +Verify your remotes: +- `origin` points to your personal fork (`https://github.com//problemspot.git`) +- `upstream` points to the primary repository (`https://github.com/geekinks/problemspot.git`) ### Install dependencies @@ -129,68 +131,82 @@ npm run dev Follow the README and existing project scripts if they differ from these examples. -## Contribution Workflow +## Mandatory Contribution Workflow -### 1. Choose or discuss the work +All contributors (including maintainers and automated pair-programming agents) must follow this strict 5-step lifecycle. **Direct commits or pushes to `main` are strictly prohibited.** -- For a bug, describe the expected and actual behavior and how to reproduce it. -- For a feature, explain the user problem, the proposed solution, and any trade-offs. -- For a database or security change, explain its effect on data access, privacy, and existing records. -- For AI changes, describe how quality will be evaluated and what happens when the model is unavailable or uncertain. - -### 2. Create a focused branch - -Start from the latest default branch: - -```bash -git checkout main -git pull upstream main -git checkout -b feat/short-description +```mermaid +flowchart LR + A["1. Issue on Main Repo
(geekinks/problemspot)"] --> B["2. Fork & Dedicated Branch
(origin: feat/xyz)"] + B --> C["3. Implement & Test
(Conventions & Linting)"] + C --> D["4. Open PR to Main
(Closes #...)"] + D --> E["5. Review & Squash Merge
(Wait for merge)"] ``` -Use the actual default branch if it is not `main`. Suggested branch prefixes: - -- `feat/` — new functionality -- `fix/` — bug fixes -- `docs/` — documentation -- `test/` — tests -- `refactor/` — internal improvements -- `chore/` — maintenance and tooling - -Keep each branch focused on one logical change. - -### 3. Make and verify your changes - -- Follow the existing code patterns and conventions. -- Add or update tests where appropriate. -- Update documentation when behavior, setup, environment variables, or API contracts change. -- Add database changes as version-controlled Supabase migrations. -- Test relevant permissions and RLS policies with the roles affected by the change. -- Do not include unrelated formatting changes or generated files unless required. - -### 4. Commit your work - -Use clear, descriptive commit messages. Conventional Commit-style messages are encouraged: - -```text -feat: add problem category filters -fix: prevent duplicate community votes -docs: clarify local Supabase setup -test: cover problem status transitions -refactor: isolate AI provider adapter -``` - -Keep commits understandable and avoid bundling unrelated changes. - -### 5. Push and open a pull request - -```bash -git push origin feat/short-description -``` - -Open a pull request against the project's default branch. Complete the pull request template, explain the change, link related issues, and include screenshots or recordings for UI changes when useful. - -Be ready to respond to review feedback and make follow-up changes. A review is a collaborative quality check, not a personal judgment. +### 1. Check Existing Issues or Open a New Issue +- **All issues must be opened on the upstream repository:** [`geekinks/problemspot/issues`](https://github.com/geekinks/problemspot/issues). +- Before writing any code, search open issues with `gh issue list --repo geekinks/problemspot`. +- If no issue covers your proposed work, open one with `gh issue create --repo geekinks/problemspot` to align on requirements, user problem, and technical approach. +- **Unsolicited PRs without an associated issue will not be reviewed.** + +### 2. Fork the Repository and Create a Dedicated Branch +- If you haven't already, fork the repository using the GitHub CLI or web UI: + ```bash + gh repo fork geekinks/problemspot --clone=false --remote=true + ``` +- Always sync your local default branch (`main`) with `upstream/main` before creating a new branch: + ```bash + git checkout main + git pull upstream main + git checkout -b / + ``` +- **Branch naming conventions:** + - `feat/` — new user-facing functionality or enhancement + - `fix/` — bug fixes + - `docs/` — documentation, guides, or specifications + - `design/` — design system tokens, wireframes, or UI assets + - `test/` — automated unit, integration, or e2e tests + - `refactor/` — internal code quality improvements without behavioral changes + - `chore/` — maintenance, tooling, dependencies, and configuration +- Keep each branch focused on one logical issue. Never commit directly to `main`. + +### 3. Make and Verify Your Changes Locally +- Adhere to [`brand.md`](brand.md) visual standards and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) design boundaries. +- Follow TypeScript strict typing; avoid `any`. +- Run static analysis, linting, and tests locally before committing. Ensure 0 errors and all tests pass: + ```bash + npm run lint + npm test + ``` +- Commit using Conventional Commits with clear scope: + ```text + feat(problems): implement problem submission wizard with category select + fix(voting): prevent duplicate personal confirmation entries + docs(contributing): formalize fork and PR contribution workflow + test(auth): add RLS policy verification tests + ``` + +### 4. Push to Fork and Open a Pull Request +- Push your dedicated branch to your personal fork (`origin`): + ```bash + git push -u origin / + ``` +- Open a Pull Request targeting `geekinks/problemspot:main` referencing the issue: + ```bash + gh pr create --repo geekinks/problemspot --title "(): " --body "Closes #" + ``` +- Complete the PR description detailing the problem solved, testing performed, and UI screenshots/recordings if applicable. + +### 5. Review, CI Verification, and Squash Merge +- **Do not merge directly.** Wait for automated CI checks and maintainer review. +- Respond constructively to review feedback and push adjustments to your branch as needed. +- Once approved and CI passes, maintainers will squash-merge the PR into `main` and delete the remote branch. +- After merge, switch back to `main`, sync locally, and clean up your feature branch: + ```bash + git checkout main + git pull upstream main + git branch -d / + ``` ## Code and Documentation Guidelines diff --git a/README.md b/README.md index fad0458..f41895d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,20 @@ # ProblemSpot -**Report It. Validate It. Solve It.** +

+ ProblemSpot Logo +

+ +

+ Real Community Problems. Together, Real Solutions.
+ Report It. Validate It. Solve It. +

+ +

+ License: MIT + Hacktoberfest 2026 + Open Issues + Open PRs +

ProblemSpot is an open-source, AI-assisted community problem discovery and validation platform. It helps people report challenges affecting @@ -12,10 +26,12 @@ opportunities to build solutions. > the needs. AI assists the process. Contributors build the solutions. > Communities measure the impact. -**Organization:** GeekInk Innovations Ltd\ -**Initiative:** Hacktoberfest 2026 --- AI for Everyone\ -**Repository:** `problemspot`\ -**Proposed domain:** `problemspot.tech` (availability not verified) +- **Organization:** GeekInk Innovations Ltd +- **Initiative:** Hacktoberfest 2026 — AI for Everyone +- **Repository:** [`geekinks/problemspot`](https://github.com/geekinks/problemspot) +- **Primary Domain:** [`problemspot.tech`](https://problemspot.tech) *(Secured)* +- **Backup Mirror:** `problemspot.org` *(Reserved)* +- **Topics & Tags:** `hacktoberfest`, `agent`, `community`, `ai`, `open-source`, `problem-solving` ------------------------------------------------------------------------ diff --git a/docs/PRD.md b/docs/PRD.md index 04e072f..5ce28c7 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -1,14 +1,15 @@ # ProblemSpot — Product Requirements Document (PRD) -**Version:** 1.0 -**Status:** Draft for Development -**Project Type:** Open-Source, AI-Powered Community Innovation Platform -**Repository:** `problemspot` -**Proposed Domain:** `problemspot.tech` -**Initiative:** Hacktoberfest 2026 — AI for Everyone -**Organization:** GeekInk Innovations Ltd +**Version:** 1.0\ +**Status:** Draft for Development\ +**Project Type:** Open-Source, AI-Powered Community Innovation Platform\ +**Repository:** [`geekinks/problemspot`](https://github.com/geekinks/problemspot)\ +**Primary Domain:** [`problemspot.tech`](https://problemspot.tech) *(Secured)* | **Backup:** `problemspot.org`\ +**Initiative:** Hacktoberfest 2026 — AI for Everyone\ +**Organization:** GeekInk Innovations Ltd\ **Tagline:** Report It. Validate It. Solve It. + --- ## 1. Executive Summary