From 1cdce70c5a6de91788f79ae5639744e4fd0e0bd6 Mon Sep 17 00:00:00 2001 From: ummaraali2 Date: Thu, 11 Jun 2026 22:18:20 -0400 Subject: [PATCH] Add contributing guide with trusted contributor roles. --- CONTRIBUTING.md | 192 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 6 +- 2 files changed, 193 insertions(+), 5 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d599411 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,192 @@ +# Contributing to PostScholar + +Thank you for your interest in PostScholar. This project is an open academic discussion platform built around published papers, ORCID-verified authorship, and thoughtful discourse. + +This guide covers how to set up a local environment, propose changes, and meet the standards we expect before a pull request is merged. + +## Before you start + +- Read the [README](README.md) for an overview. +- Follow the [Developer Guide](docs/DEVELOPER_GUIDE.md) for local setup, migrations, and deployment. +- Production site: [postscholar.org](https://postscholar.org) +- Repository: [github.com/PostScholar/postscholar](https://github.com/PostScholar/postscholar) + +## Ways to contribute + +You do not need to write code to help: + +- **Report bugs** — open a GitHub issue with steps to reproduce, expected vs actual behavior, and browser/OS if relevant. +- **Suggest improvements** — describe the problem and proposed behavior; UI mockups or screenshots help. +- **Improve documentation** — fixes and clarifications in `docs/` and this file are welcome. +- **Code** — features, bug fixes, tests, and tooling (see below). + +## Local development + +### Prerequisites + +- Node.js 18+ +- PostgreSQL 14+ +- npm + +### Setup (summary) + +```bash +git clone https://github.com/PostScholar/postscholar.git +cd postscholar +npm install +cd server && npm install +cd ../client-next && npm install +cd .. + +cp server/.env.example server/.env +# Edit server/.env — see server/.env.example + +createdb postscholar # or equivalent +npm run migrate + +# client-next/.env.local +# NEXT_PUBLIC_API_URL=http://localhost:3000 + +npm run dev +``` + +- Frontend: [http://localhost:3001](http://localhost:3001) +- API: [http://localhost:3000](http://localhost:3000) + +Full details: [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md). + +## Branch and pull request workflow + +The `main` branch is protected. **All changes go through a pull request**; direct pushes to `main` are not allowed. + +1. Fork the repository (or create a branch if you are a collaborator). +2. Create a branch from `main` with a short, descriptive name: + - `fix/login-cookie-on-safari` + - `add/terms-page` + - `docs/update-migration-guide` +3. Make your changes and commit. +4. Push and open a PR against `main`. +5. Wait for CI to pass (`server` and `client` jobs). +6. Address review feedback if any. +7. Merge when approved and green. + +Dependabot opens its own dependency PRs; maintainers triage those separately. + +## Before opening a PR + +Run these locally: + +```bash +npm test # server tests (requires local Postgres + migrated test DB) +npm run lint # ESLint for server and client-next +``` + +If you changed frontend UI, manually check the affected pages in the browser. + +If you added or changed a database schema: + +1. Add a new numbered SQL file under `server/db/migrations/` (e.g. `019_description.sql`). +2. Use idempotent SQL where possible (`IF NOT EXISTS`, etc.). +3. Run `npm run migrate` locally and note the migration in your PR description. + +**Do not commit** `.env`, secrets, API keys, or credentials. + +## Code conventions + +Match the existing codebase rather than introducing new patterns. + +### General + +- Keep changes focused — one logical change per PR when possible. +- Prefer extending existing components, routes, and utilities over duplicating logic. +- Comments only where behavior is non-obvious; code should mostly speak for itself. + +### Frontend (`client-next/`) + +- Next.js App Router; pages in `src/app/`. +- React components in `src/components/`. +- **CSS Modules** for component styles (`.module.css`). +- API calls through `src/lib/api.js`; browser requests use the `/api` proxy (see `src/lib/config.js`). +- Use `'use client'` only when the component needs client-side state or effects. + +### Backend (`server/`) + +- Express routes in `server/routes/`. +- Auth via `authenticateToken`; moderator-only routes use `requireModerator`. +- Parameterized SQL only — never interpolate user input into queries. +- Comment bodies are sanitized server-side (`sanitize-html`). +- New routes: register in `server/index.js`. + +### Commits + +Write clear commit messages in the imperative mood: + +``` +Fix rate limiting behind Railway proxy. + +Add Terms of Service page and footer link. + +Update Developer Guide with Resend setup steps. +``` + +Squashing is optional; the PR title and description should summarize the change for reviewers. + +## Pull request description + +Include: + +- **What** changed (brief summary). +- **Why** (bug, feature, or doc improvement). +- **How to test** — steps a reviewer can follow. +- **Screenshots** for UI changes. +- **Migrations** — filename and whether `migrate:railway` is needed on deploy. + +## Testing + +Server tests live in `server/tests/`. CI runs them against Postgres 16 with migrations applied. + +- `auth.test.js` — registration, login +- `papers.test.js` — paper lookup (CrossRef test runs only when `CI=true`) +- `social.test.js` — follows, mentions, reports + +Add or update tests when fixing bugs or adding API behavior. Frontend automated tests are not required yet but are appreciated if they fit the change. + +## Community and moderation + +PostScholar is intended for good-faith academic discussion: + +- Be respectful; disagree on ideas, not people. +- Do not harass users or post spam. +- Report problematic content via the in-app report flow; moderators review reports at `/moderation`. + +We reserve the right to decline contributions that undermine community safety or project goals. + +## Trusted contributors and project roles + +PostScholar is maintained by a small core team. Contributors who make **sustained, high-quality contributions** over time — merged PRs, thoughtful reviews, documentation, bug reports with clear reproduction steps, and respectful participation in issues — may be **considered for expanded access**. + +This is always **by invitation**, based on trust and fit with the project. It is not automatic and is not tied to a specific number of PRs. + +Expanded roles may include: + +- **Repository collaborator** — help triage issues and review pull requests on GitHub. +- **Moderator** (in-app) — access to the moderation queue at `/moderation` to review user reports. +- **Admin** (in-app) — broader operational responsibilities as defined by the maintainers. + +If you are interested in a maintainer or moderation role after you have an established contribution history, contact [hello@postscholar.org](mailto:hello@postscholar.org) or reach out to an existing maintainer on GitHub. Final decisions rest with the project owners. + +## Security + +If you discover a security vulnerability, **do not** open a public issue with exploit details. Email [hello@postscholar.org](mailto:hello@postscholar.org) with a description and steps to reproduce. We will respond as soon as we can. + +## License + +By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE) that covers this project. + +## Questions + +- **Setup / deploy:** [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) +- **Architecture notes:** [docs/DEVELOPER_NOTES.md](docs/DEVELOPER_NOTES.md) +- **Everything else:** open a GitHub issue or discussion on the repository. + +Thank you for helping build a better place to discuss published research. diff --git a/README.md b/README.md index 0875e1e..5c6da1e 100644 --- a/README.md +++ b/README.md @@ -140,11 +140,7 @@ postscholar/ ## Contributing -1. Fork the repository -2. Create a feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -m 'Add amazing feature'`) -4. Push to the branch (`git push origin feature/amazing-feature`) -5. Open a Pull Request +See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, PR workflow, code conventions, and community guidelines. ## License