Thank you for your interest in contributing to DevTrack! DevTrack is a developer productivity and career readiness platform that combines DSA tracking, project management, resume intelligence, readiness analytics, and gamification.
We welcome meaningful contributions that improve correctness, reliability, accessibility, performance, security, documentation, and developer experience.
This repository participates in Nexus Winter of Code (NWoC) 2026 only where confirmed by the project maintainer. Programme-specific rules below apply to contributions submitted under NWoC 2026.
- Code of Contribution
- Repository Layout
- Getting Started
- Development Conventions
- Testing Requirements
- NWoC 2026 Issue Labels and Points
- NWoC 2026 Issue and PR Workflow
- Pull Request Requirements
- Developer Certificate of Origin (DCO)
- Code Review and Quality Control
- Commit and Branch Conventions
- Security and Environment Variables
- Questions and Support
All contributors are expected to:
- Communicate respectfully and constructively.
- Read the relevant documentation before starting work.
- Work on an issue assigned to them before submitting a pull request.
- Submit focused changes that solve the issue's stated problem.
- Write maintainable code and appropriate tests.
- Respond to review feedback and explain significant design decisions.
- Avoid duplicate, misleading, unrelated, or artificially inflated contributions.
- Respect the project's security, licensing, and contribution requirements.
A pull request is not guaranteed to be accepted simply because it contains code. Every contribution must provide meaningful value and pass the applicable review requirements.
DevTrack is organised as a monorepo.
| Directory | Stack | Responsibility |
|---|---|---|
backend/ |
Express 5, TypeScript, Mongoose, BullMQ, Clerk | API server, domain modules, and background workers |
frontend/ |
React 19, Vite, TypeScript, Zustand, Tailwind CSS 4 | Web application and user interface |
dev-orchestrator/ |
TypeScript | Local development orchestration |
docs/ |
Markdown | Architecture, deployment, and operational documentation |
Codex/ |
Project reference documentation | AI-assisted development context and project maps |
Follow the existing architecture and module conventions when adding or modifying functionality.
- Node.js 22.13.0 or newer in the 22 series, or 24.0.0+. The locked frontend dependencies do not support Node 23.
- npm 9 or later.
- Docker Desktop for local MongoDB and Redis.
- Git and a GitHub account.
- Clerk development credentials for authenticated application flows.
Some integrations and AI features require optional API credentials.
-
Fork the repository on GitHub.
-
Clone your fork and enter the repository:
git clone https://github.com/<your-username>/DevTrack.git cd DevTrack
-
Install dependencies:
npm run install-all
-
Create local environment files:
cp backend/.env.example backend/.env cp frontend/.env.example frontend/.env
On Windows PowerShell, use
Copy-Itemifcpis unavailable. -
Configure the required variables using your own development credentials:
backend/.env:CLERK_SECRET_KEYfrontend/.env:VITE_CLERK_PUBLISHABLE_KEYfrontend/.env:VITE_API_BASE_URL
The documented local API base URL is
http://localhost:3001/api. -
Start MongoDB and Redis:
npm run dev:infra
-
Start the application:
npm run dev
To start the full stack with workers, use:
npm run dev:all
Windows contributors can also use:
.\start-dev.ps1
Refer to the main README and docs/ for further setup details. Verify the available scripts in the relevant package.json before running commands if the repository has changed.
Backend feature modules belong under:
backend/src/modules/<module-name>/
├── index.ts
├── <module-name>.routes.ts
├── <module-name>.controller.ts
├── <module-name>.service.ts
└── <module-name>.validation.ts
Follow these conventions:
- Register new API routes in
backend/src/routes/index.ts. - Mount API routes under
/api/v1unless an existing compatibility requirement dictates otherwise. - Validate external request inputs with Zod.
- Use the existing authentication middleware for protected routes.
- Follow established error-handling and
asyncHandlerpatterns. - Use the shared logger instead of
console.log. - Prefer
.lean()for suitable read-only Mongoose queries. - Use atomic database updates where appropriate.
- Consider indexes, pagination, validation, and query performance when modifying data access.
- Follow existing BullMQ worker, retry, and failure-handling conventions.
- Use existing components and feature modules before introducing new abstractions.
- Place generic UI primitives under
frontend/src/components/ui/. - Place domain-specific functionality under
frontend/src/features/. - Keep route-level pages under
frontend/src/pages/. - Use the existing Axios service modules for API requests instead of introducing raw
fetchcalls that bypass established patterns. - Use TanStack Query for server state and Zustand for appropriate client-side UI state.
- Reuse the existing SSE hook for real-time updates. Do not create separate
EventSourceconnections in individual components when the shared hook is appropriate. - Follow the Tailwind CSS 4 design tokens and existing design-system conventions.
- Use the established motion system rather than introducing arbitrary animation values.
- Ensure interactive components are keyboard-accessible and provide appropriate accessible names and states.
- Keep changes scoped to the assigned issue.
- Avoid unnecessary dependencies and unrelated refactoring.
- Follow existing TypeScript and naming conventions.
- Update documentation when behaviour, configuration, or public interfaces change.
- Do not commit credentials, generated artifacts, local environment files, or unrelated formatting changes.
Choose tests appropriate to the change.
Run from the backend/ directory:
npm run build
npm run test:unit
npm run test:integrationIntegration tests provision a fresh temporary MongoDB instance per test file using
mongodb-memory-server (also used by the unit suite). Do not set MONGODB_URI in
the shell or CI when running them: inherited URIs are rejected before connection,
even if the database name contains test. The application .env URI is overridden
before application modules load. Only the owned instance's fixtures are cleared;
teardown stops that instance and removes its temporary files without dropping a
database on a shared server. The first run may download MongoDB 7.0.14; an existing
binary can be selected with MONGOMS_SYSTEM_BINARY.
Redis is still required for full integration coverage. URI/ownership regression
tests run without database infrastructure via npm run test:safety and are also
included in npm run test:unit.
Run from the frontend/ directory:
npm run build
npm run test:unitEnd-to-end tests require the running application stack:
npm run test:e2e- Add or update tests for changed behaviour.
- Include regression coverage for bug fixes where practical.
- Test relevant success and failure cases.
- Clean up database connections, timers, and other resources in tests.
- Avoid tests that depend unnecessarily on external services or live AI API credentials.
- Do not weaken or delete existing tests simply to make CI pass.
- Report any checks that could not be run and explain why.
Check the current package scripts and CI workflow for the authoritative commands.
For issues and pull requests submitted under the programme, the following four labels are mandatory.
| Label | Points | Intended scope |
|---|---|---|
nsoc26 |
Mandatory tag | Every programme issue and PR |
level1 |
3 | Documentation, typo fixes, and other small tasks |
level2 |
5 | UI, frontend components, layouts, styling, and page-level changes |
level3 |
10 | Core logic, database changes, and complex features |
The point values above follow the supplied programme guidelines. The maintainer assigns the appropriate level based on the actual complexity of the task.
- Every programme issue must have the
nsoc26label and exactly one level label. - Programme pull requests must have the
nsoc26label and the appropriate level label before merging. - Do not assign Level 2 or Level 3 to a task that is genuinely a small documentation or typo fix.
- Maintainers must assign levels consistently and honestly.
- Add the required labels promptly. Do not leave merged programme PRs unlabelled.
- If a programme PR is missing
nsoc26, request that the contributor correct it before merging. - Optional labels such as
good first issue,help wanted,bug,feature, anddocsmay be used alongside the mandatory labels.
The level label determines the programme points according to the supplied guidelines. Creating GitHub labels alone does not automatically award points.
The following workflow applies to programme contributions.
Before starting work, identify an existing issue or open a new issue describing the proposed change.
An issue should contain:
- A clear title and problem statement.
- Relevant context and reproduction steps for bugs.
- Expected behaviour or acceptance criteria.
- The likely affected modules or files, where known.
- Testing expectations.
- The mandatory programme and level labels.
Do not begin a substantial change without maintainer approval and assignment.
Contributors must wait for the maintainer to assign the issue before starting work.
Under the supplied NWoC guidelines, pull requests submitted without the required issue assignment are invalid and must be closed.
Maintainers should check for duplicate issues, confirm scope, select the appropriate level, and assign work before accepting a contribution.
Contributors should communicate progress and raise blockers promptly.
If an assigned contributor is inactive for seven days, the maintainer will unassign the issue according to the programme rules. The issue may then become available to another contributor.
Create a dedicated branch for each assigned issue.
Examples:
git checkout -b feat/dsa-heatmap-filter
git checkout -b fix/sse-reconnect
git checkout -b docs/deployment-guideKeep unrelated changes out of the branch.
Open a PR against the appropriate base branch and reference the assigned issue using GitHub's closing syntax:
Closes #<issue-number>
For example:
Closes #42
Include a concise summary, implementation details, relevant testing results, and any known limitations.
Maintainers will:
- Confirm the PR corresponds to an assigned issue.
- Verify that the change is relevant and meaningful.
- Review the implementation and test coverage.
- Check applicable CI results and repository quality requirements.
- Request corrections where necessary.
- Add the required
nsoc26and level labels. - Merge only after the applicable requirements are satisfied.
Maintainers must watch for fake PRs, bulk PRs, and AI-generated PRs that do not represent genuine contributions. Such submissions must not be merged under the programme rules.
AI tools may be used as development aids where permitted, but they do not replace understanding, testing, attribution, or meaningful human contribution. Follow any additional programme-specific AI policy.
Before requesting review, confirm that:
- The PR addresses an assigned issue.
- The PR contains only changes relevant to that issue.
- The issue is linked using
Closes #<issue-number>. - Backend and frontend builds pass where applicable.
- Relevant unit and integration tests pass.
- Tests have been added or updated for changed behaviour where appropriate.
- No debug statements, accidental generated files, or unrelated commented-out code remain.
- New routes are registered correctly and documented when public-facing.
- Environment variable changes are reflected in the appropriate
.env.examplefile. - No secrets or credentials have been committed.
- The PR includes a clear summary and testing evidence.
- All commits include a valid Developer Certificate of Origin (DCO) sign-off (
git commit -s). - The required NWoC labels are applied before merging.
To safeguard the intellectual property rights of contributors and downstream users, DevTrack enforces the Developer Certificate of Origin (DCO) Version 1.1.
DevTrack accepts contributions under the repository's MIT Licence, subject to the contributor possessing the legal rights to make that submission. Every future contribution submitted to this repository must include a valid DCO sign-off trailer.
The full, official text of the Developer Certificate of Origin 1.1 (also available at developercertificate.org) is provided below:
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
When submitting contributions:
- Licensing Certification: By signing off, you certify that you created the work or have the legitimate legal right to submit it under the project's MIT Licence.
- No Copyright Assignment: Signing the DCO does not transfer or assign copyright ownership to DevTrack, the maintainer, or any third party. Contributors retain copyright in their original creative work while licensing it under the terms of the project's MIT Licence.
- No Incompatible or Unlicensed Code: You must not submit code copied or adapted from proprietary, incompatible, or unlicensed external sources.
- Attribution & Notices: You must retain all applicable third-party copyright notices, license headers, and attribution metadata for any permissible third-party code.
- Identity Integrity: You must sign off using your own real name or recognized identity and verifiable email. You must never sign off on behalf of another individual.
- Quality Gates: DCO sign-off does not replace code review, automated testing, security validation, or other repository contribution requirements.
- Non-Retroactivity Notice: DCO sign-off applies to all commits submitted moving forward. DCO sign-off does not retroactively resolve licensing permissions or provide automatic copyright assignment for contributions merged before this policy was enacted.
Configure your Git author identity so that it reflects your real name and email:
git config user.name "Your Name"
git config user.email "your-email@example.com"When creating a commit, pass the -s (or --signoff) flag:
git commit -s -m "feat(scope): describe your change"This automatically appends a standard Signed-off-by trailer to the end of your commit message:
feat(dsa): add topic progress analytics
Signed-off-by: Contributor Name <contributor@example.com>
If you have already committed changes locally without signing off:
If only the most recent commit is missing a sign-off:
git commit --amend -s --no-editIf multiple commits in your pull request require sign-offs, rebase interactively to add the sign-off trailer across the range:
git rebase -i --signoff <base-branch-or-commit>Warning
Do not rewrite or force-push commits that have already been shared with others or merged into shared branches without coordinating first.
If a commit represents pair programming or collaborative work across multiple contributors:
- Add standard
Co-authored-by:trailers for each co-author. - In addition, each co-author must also provide a corresponding
Signed-off-by:trailer certifying their contribution under DCO 1.1:
feat(dsa): add graph traversal engine
Co-authored-by: Bob Partner <bob@example.com>
Signed-off-by: Alice Author <alice@example.com>
Signed-off-by: Bob Partner <bob@example.com>
A Co-authored-by: trailer alone does not constitute a legal certification or DCO sign-off.
Maintainers and reviewers should verify the following.
- Does the implementation solve the issue's stated problem?
- Are edge cases and failure paths handled?
- Is the change consistent with existing application behaviour?
- Are external inputs validated?
- Are authentication and authorization requirements preserved?
- Are secrets protected?
- Are database operations and API endpoints safe?
- Does the change follow existing module and component patterns?
- Are responsibilities separated appropriately?
- Are unnecessary dependencies or abstractions avoided?
- Is the documentation consistent with the implementation?
- Are database indexes and query patterns appropriate?
- Are background jobs, retries, and failure handling correct?
- Are real-time connections and subscriptions managed properly?
- Are resources cleaned up in tests and application code?
- Review the relevant CI checks before merging.
- Require corrections for failing tests or significant review findings.
- Do not merge work solely to award programme points.
- Do not merge fake, duplicate, bulk, or otherwise invalid submissions.
- Keep feedback specific, respectful, and actionable.
Use descriptive branch names.
| Type | Pattern | Example |
|---|---|---|
| Feature | feat/<description> |
feat/dsa-heatmap-filter |
| Bug fix | fix/<description> |
fix/sse-reconnect |
| Documentation | docs/<description> |
docs/deployment-guide |
| Hardening | harden/<description> |
harden/rate-limit-sync |
Follow conventional commit messages:
feat(readiness): add roadmap gap analyzer
fix(auth): correct Clerk token validation on SSE
chore(repo): update deployment documentation
test(ops): add dead-letter queue resilience cases
Use concise, descriptive commit messages that explain the change.
- Never commit
.envfiles, access tokens, passwords, private keys, or other secrets. - Use the supplied
.env.examplefiles as templates. - Use your own development credentials.
- Do not include real user data or sensitive production information in tests or issues.
- Report suspected vulnerabilities privately through an appropriate maintainer or repository security contact rather than publicly disclosing exploitable details.
- Do not weaken authentication, authorization, rate limiting, or validation to make a feature easier to implement.
Before asking for help:
- Read this guide and the relevant documentation.
- Search existing issues and pull requests for related discussions.
- Check the setup instructions and applicable test commands.
- Provide a concise explanation of the problem, the steps attempted, and any relevant error output.
For contribution questions, open an appropriately labelled issue or use the repository's designated support channel.
Thank you for helping make DevTrack more reliable, useful, and welcoming to developers.
Maintainer note: Before opening the repository to external contributions, ensure the project's licence and contribution terms clearly permit the intended contributions. Programme participation and the availability of a public repository do not, by themselves, establish an open-source licence.