/.github/CONTRIBUTING.md
We are lucky to have you! 🎉👍
The following is a set of guidelines for contributing to this project. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a merge request.
This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.
Perfect 👍 — here’s the updated and polished CONTRIBUTING.md for your Need4Deed GitHub organization, now reflecting:
- Migration from GitLab → GitHub
- Your current setup with
fe,be, andsdk - SDK linking workflow
- Mention that designs are in Figma and must be followed
- Clearer instructions for newcomers
Thank you for your interest in contributing to Need4Deed! We’re building tools that empower people to do good — and every contribution helps. 💪
Not sure where to start?
Look through good first issues labeled good first issue in the appropriate repository.
Our main repositories:
| Repository | Description |
|---|---|
fe |
Next.js PWA — main app for automating Need4Deed processes |
be |
Node.js / TypeScript API for the app |
sdk |
Shared TypeScript types and utilities between FE and BE |
website |
React/Vite static landing page (currently frozen) |
- Go to the repo you want to contribute to (e.g.
fe) - Click Fork (top-right)
- Select your GitHub account as the destination
We prefer using yarn. You may use other package manager, but please make sure:
pre-commitscript is invoked before committing- do not clutter a repo with a lock file other than
yarn.lock yarn.lockis up to date.
git clone https://github.com/<your-username>/<repo-name>.git
cd <repo-name>
yarn installgit remote add upstream https://github.com/need4deed-org/<repo-name>.git
git remote -vYou should see:
origin→ your forkupstream→ the official Need4Deed repository
git checkout -b your_nick-feature-titleExample:
git checkout -b anna-fix-login-form
We maintain three sibling repositories that work closely together:
parent/
├── fe/ # Frontend (Next.js PWA)
├── be/ # be (API)
└── sdk/ # Shared types and helpers
SDK is published on https://www.npmjs.com/package/need4deed-sdk make sure you're on the latest if you're working on API related issues:
$ yarn upgrade need4deed-sdk --latest
The sdk is the single source of truth for the API contract. Any change to the API surface
(endpoints, request/response shapes, types, error codes) MUST follow this order:
- Discuss and update id needed the contract in the
sdkrepo first. - Publish the new SDK version to npm.
- Only then update
beandfeto consume the change.
IMPORTANT: be and fe MUST depend on the SDK as published on npmjs.com — never on the
local sdk checkout or a sibling folder. Do not use file:../sdk, npm link, workspace or
link: references, or any other local linking for the SDK dependency. Pin to a version that is
actually published. If the version you need isn't on npmjs.com yet, the work is not ready to
land in be/fe — finish and publish the SDK first!!!
Do not implement or "stub" an API change in be or fe ahead of the contract. If the contract is
missing, wrong, or incomplete, fix it in sdk and publish — never work around it locally.
Always make sure all API related issues are based on the latest dependency "need4deed-sdk". > 🔄 if you get TypeScript errors, make sure sdk and be or fe are aligned and freshly pulled.
Please ensure all code changes directly address the issue. Minor flaws, such as a typo, may be corrected; however, if you make such corrections, please note them in the PR comments.
git push origin your_nick-feature-titlethen go to the forked repo on your GitHub account and open the PR.
And please make sure your opened PR is wired with the issue by using a keyword, e.g. closes followed by the link to the issue: #<number of issue>
All UI and UX designs are maintained in Figma. Before implementing any new feature or layout change:
- Always refer to the Figma file shared by the design team
- Match the spacing, typography, and component structure
- Discuss any deviations with the design lead before committing
Consistency between Figma and implementation helps ensure a unified user experience.
- FE is a Next.js progressive web app (PWA)
- You can manually test a page by visiting its URL directly
- The legacy website (Vite) remains online but is frozen
- Future plan: merge the landing page into the
feapp
Before submitting a bug:
- Check if it’s already reported under Issues in the relevant repository
If not, open a new issue using the bug report template.
Feature requests are tracked as GitHub issues too. Use the feature request template in the appropriate repo.
- Use present tense (“Add feature” not “Added feature”)
- Use imperative mood (“Fix bug” not “Fixes bug”)
- Keep the first line under 72 characters
- Include related issue numbers if applicable
Use emoji prefixes when relevant:
- 🎨
:art:— improve structure or formatting - 🐎
:racehorse:— performance improvement - 📝
:memo:— docs update - 🐛
:bug:— fix a bug - 🔥
:fire:— remove code or files
By contributing, you agree that your contributions are licensed under our Commons Clause + MIT License.
Need help or clarification?
- Open an issue in the relevant repository
- Tag a maintainer (e.g.,
@arturas) - Or email us at sowtware@need4deed.org to request Slack access
Any contributions are welcome! 🙏