Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
137 lines (96 loc) · 6.29 KB

CONTRIBUTING.md

File metadata and controls

137 lines (96 loc) · 6.29 KB
Raw

🤝 Contributing to VeriWorkly

First off, thank you for considering contributing to VeriWorkly! We are building a professional, privacy-first career ecosystem, and we value your help.

Important

Detailed guides, developer workflows, and coding standards live in our official documentation:

⚡ Contribution Workflow

Follow these steps to contribute code or documentation to VeriWorkly:

1. Star the Repository 🌟

Before getting started, please star our repository to show your support for the project!

2. Claim an Issue 📋

  • Browse our open issues.
  • If you find an issue you want to work on, comment on it expressing your interest and wait to be officially assigned by a maintainer.
  • ⚠️ Do not start coding or open a Pull Request before being assigned to the issue.
  • Strict Issue Claiming & Pull Request Rules:
    • Claim Before Coding: You must officially claim and be assigned an issue before you start working on it or submit a Pull Request.
    • Priority for Rule Followers: If a contributor submits a PR without being assigned to the issue, and another contributor subsequently requests to claim/work on that issue following the correct procedure (commenting on the issue to request assignment), priority will be given to the contributor who requested the claim.
    • Unassigned PR Procedure: If a PR is opened without an associated claim/assignment, maintainers will post a comment on the corresponding issue directing the author to claim it.
    • 7-Day Grace Period: Maintainers will wait for up to 7 days for the PR author to claim the issue. If the author fails to comment on the issue and claim it within 7 days, the PR may not be merged (even if the code is correct) and may be closed.
    • Claim Priority: If another contributor claims the issue during this grace period, the contributor who officially requested the claim will be considered first.

3. Fork & Clone 🍴

  1. Fork the original repository.
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/veriworkly.git
cd veriworkly
  3. Set up the upstream remote: 
    git remote add upstream https://github.com/VeriWorkly/veriworkly.git

4. Branching Policy 🌿

  • PRs must be based on and target the master branch.
  • Keep your fork in sync and create a descriptive feature branch: 
    git checkout master
git pull upstream master
git checkout -b feat/your-feature-name
  • Branch Naming Convention:
    • feat/feature-name (new features/enhancements)
    • fix/bug-name (bug fixes)
    • docs/doc-update (documentation changes)
    • refactor/scope-of-work (restructuring/refactoring code)

5. Local Setup & Verification 🛠️

  • Install dependencies: npm install
  • Copy each app's .env.example to .env in the same folder. The steps are in the README, and each variable is described in its .env.example.
  • Run what your change touches:
    • Marketing site only (port 3000): npm run dev:site
    • Studio only (port 3001, guest mode needs no API): npm run dev:studio
    • With the API: set DATABASE_URL and REDIS_URL in apps/server/.env, run npm run db:migrate, then npm run dev:server next to the app you are testing.

Why the root package.json lists Linux binaries

optionalDependencies in the root package.json names the Linux x64 native binaries of esbuild, Rolldown, Tailwind's oxide and Lightning CSS. A lockfile written on Windows or macOS can leave them out, and then npm ci on Linux (CI, Docker, the VPS) installs no binary and the build fails. Listing them keeps them in package-lock.json. Other platforms skip them. Do not remove them.

📝 Pull Request Guidelines

To ensure smooth reviews and fast merges, please adhere to these PR guidelines:

1. PR Title Naming Convention

PR titles must follow the format:

[Type] [App/Component]: <lowercase description>
  • Type: [Fix], [Feature], [Refactor], [Docs], [Chore]
  • App/Component: [Studio], [Server], [Site], [UI], etc.
  • Example: [Fix] [Studio]: hide auth-only actions in account menu for anonymous users

2. Linking Issues

  • You must link the issue your PR addresses in the PR description using the hashtag format (e.g., Fixes #123 or Closes #123). This allows GitHub to automatically associate and close the issue upon merge.

3. Complete the PR Template & Checklist

  • When opening a PR, fill out the template fully.
  • Complete the checkbox checklist in the PR body by replacing [ ] with [x] for items you have done (e.g., linting, formatting, tests).
  • ⚠️ PRs with empty, uncompleted checklists will not be reviewed.

✍️ Sign your commits (DCO)

We use the Developer Certificate of Origin. It is a one-line sign-off, not a contributor licence agreement. You keep the copyright in your work, and there is no paperwork to sign or email to us.

Add a Signed-off-by line to each commit:

Signed-off-by: Your Name <your.email@example.com>

git commit -s adds it for you from your configured user.name and user.email. To fix an existing commit, use git commit --amend -s; for several, git rebase --signoff.

By signing off you are certifying the DCO: that you wrote the change, or have the right to submit it under this project's licence, and that you are happy for it to be distributed under the MIT License along with your sign-off record.

Why we ask. Without it we cannot show a clear chain of provenance for the codebase, which matters if we ever need to relicense, dual-license, or defend the project's origin. The DCO closes that gap from today forward at the cost of one line per commit. It does not give us your copyright and it does not let us relicense your contribution without your agreement. See LICENSING.md.

🤝 Code of Conduct

We expect all contributors to follow our Code of Conduct. Be respectful, inclusive, and collaborative.

Built with ❤️ by VeriWorkly Team