Daniel Ioni

Posted on Jul 20

🤝 Contributing to MyZubster: Developer Guide

#tutorial #beginners #github #opensource

Complete guide for developers who want to contribute – from setup to PR
📌 What is This Guide?

This guide is designed to help developers contribute to MyZubster. Whether you're a beginner or an experienced open-source contributor, you'll find everything you need:

✅ Setup – Clone, install, and run the project

✅ Workflow – Fork, branch, commit, and PR

✅ Code standards – Style, linting, and testing

✅ PR process – What to expect and how to get merged

✅ Community – How to communicate and collaborate

🧩 Prerequisites
Requirement Version Check Command
Node.js v18+ node -v
npm v9+ npm -v
Git Latest git --version
Docker Latest (optional) docker --version
GitHub Account Free Sign up
📦 Step 1: Fork the Repository
1.1 Fork the Main Repository

Go to: github.com/DanielIoni-creator/myzubster

Click the Fork button (top right).
1.2 Clone Your Fork
bash

Clone your fork (replace YOUR_USERNAME)

git clone https://github.com/YOUR_USERNAME/myzubster.git
cd myzubster

1.3 Add Upstream Remote
bash

Add the original repository as upstream

git remote add upstream https://github.com/DanielIoni-creator/myzubster.git

Verify remotes

git remote -v

origin https://github.com/YOUR_USERNAME/myzubster.git (fetch)

origin https://github.com/YOUR_USERNAME/myzubster.git (push)

upstream https://github.com/DanielIoni-creator/myzubster.git (fetch)

upstream https://github.com/DanielIoni-creator/myzubster.git (push)

🏗️ Step 2: Setup Development Environment
2.1 Clone All Submodules
bash

Clone all submodules recursively

git submodule update --init --recursive

2.2 Install Dependencies
bash

Gateway

cd gateway
npm install
cd ..

Marketplace

cd marketplace
npm install
cd ..

AI Assistant (if working on it)

cd ai-assistant
npm install
cd ..

Mobile App (optional)

cd app
npm install
cd ..

2.3 Configure Environment Variables
bash

Gateway

cp gateway/.env.example gateway/.env

Marketplace

cp marketplace/.env.example marketplace/.env

AI Assistant

cp ai-assistant/.env.example ai-assistant/.env

Edit each .env file with your values (use your own secrets).
🔧 Step 3: Run the Project
3.1 Start MongoDB
bash

Using Docker

docker run -d -p 27017:27017 --name mongodb mongo:6

Or use local MongoDB

mongod --dbpath ~/data/db

3.2 Start All Services

Terminal 1 – Gateway:
bash

cd gateway
npm run dev

Terminal 2 – Marketplace:
bash

cd marketplace
npm run dev

Terminal 3 – AI Assistant:
bash

cd ai-assistant
npm run dev

Terminal 4 – Mobile App (optional):
bash

cd app
npm start

3.3 Verify Everything Works
bash

Gateway health check

curl http://localhost:3000/api/health

Marketplace health check

curl http://localhost:4000/api/health

AI Assistant

open http://localhost:5173

🌿 Step 4: Branching Strategy
4.1 Branch Naming Convention
Branch Type Prefix Example
Feature feature/ feature/add-pgp-encryption
Bug Fix fix/ fix/escrow-release-bug
Documentation docs/ docs/update-api-reference
Hotfix hotfix/ hotfix/security-patch
Refactor refactor/ refactor/optimize-db-queries
4.2 Create a Branch
bash

Always create from main

git checkout main
git pull upstream main

Create feature branch

git checkout -b feature/your-feature-name

📝 Step 5: Code Standards
5.1 Code Style

We follow ESLint + Prettier for JavaScript/React code.
bash

Run linter

npm run lint

Run linter with auto-fix

npm run lint:fix

Run prettier

npm run format

Configuration files:

.eslintrc.js – ESLint rules

.prettierrc – Prettier rules

.editorconfig – Editor settings

5.2 Commit Message Convention

We follow Conventional Commits:
Type Description
feat: New feature
fix: Bug fix
docs: Documentation update
style: Code style (formatting, missing semicolons)
refactor: Code refactoring
test: Adding/updating tests
chore: Maintenance tasks
ci: CI/CD changes

Examples:
text

feat: add PGP encryption for messages
fix: resolve escrow release timeout issue
docs: update API documentation for orders endpoint
refactor: optimize database queries for dashboard
test: add unit tests for escrow service

5.3 Commit Message Structure
text

():

Example:
text

feat(pgp): add key generation and encryption

Implemented PGP key generation with 4096-bit RSA
Added encrypt/decrypt functions
Integrated with user profile

Closes #123

🧪 Step 6: Testing
6.1 Run Tests
bash

Run all tests

npm test

Run tests with coverage

npm test -- --coverage

Run specific test file

npm test -- auth.test.js

Run tests in watch mode

npm test -- --watch

6.2 Write Tests

We use Jest for testing. Create tests in tests/ or tests/ folders.

Example Test:
javascript

const request = require('supertest');
const app = require('../server');

describe('Auth API', () => {
it('should register a new user', async () => {
const res = await request(app)
.post('/api/auth/register')
.send({
email: 'test@example.com',
password: 'test123',
username: 'testuser',
name: 'Test User'
});
expect(res.statusCode).toBe(201);
expect(res.body).toHaveProperty('token');
expect(res.body.user).toHaveProperty('id');
});

it('should login a user', async () => {
const res = await request(app)
.post('/api/auth/login')
.send({
email: 'test@example.com',
password: 'test123'
});
expect(res.statusCode).toBe(200);
expect(res.body).toHaveProperty('token');
});
});

6.3 Test Coverage Requirements
Metric Requirement
Statements 80%+
Branches 75%+
Functions 80%+
Lines 80%+
🔄 Step 7: Pull Request Process
7.1 Before Submitting PR
bash

Pull latest changes

git pull upstream main

Resolve conflicts if any

git merge upstream/main

Run tests

npm test

Run linter

npm run lint

Build the project

npm run build

Push to your fork

git push origin feature/your-feature-name

7.2 Create Pull Request

Go to your fork on GitHub

Click "Compare & pull request"

Fill in the PR template

Request review from maintainers

Link any related issues

7.3 PR Template
markdown

Description

Brief description of the changes.

Type of Change

[ ] Bug fix
[ ] New feature
[ ] Documentation update
[ ] Refactoring
[ ] Test
[ ] Other

Checklist

[ ] I have tested my changes
[ ] I have updated the documentation
[ ] I have added tests for my changes
[ ] All tests pass locally
[ ] My code follows the project's style guide
[ ] My commits follow the Conventional Commits spec

Related Issues

Closes #123

Screenshots (if applicable)

Add screenshots here.

Additional Context

Add any other context here.

7.4 PR Review Process
Step Who Description
1 Contributor Opens PR with description
2 CI Automated tests and linting run
3 Maintainer Reviews code and provides feedback
4 Contributor Addresses feedback and updates PR
5 Maintainer Approves and merges PR
6 CI Deploys to staging
📋 Step 8: Code Review Guidelines
8.1 What We Look For
Aspect What We Check
Functionality Does it work as expected?
Code Quality Is it clean, readable, and maintainable?
Performance Are there any bottlenecks?
Security Are there any vulnerabilities?
Testing Are there sufficient tests?
Documentation Is it well-documented?
Style Does it follow the style guide?
8.2 Giving Feedback

Be constructive – Focus on the code, not the person

Be specific – Give examples when possible

Be kind – Everyone is learning

Ask questions – Understand the intent behind the code

Suggest improvements – Offer alternatives when appropriate

8.3 Receiving Feedback

Stay open-minded – Feedback is about improving the code

Ask clarifying questions – If you don't understand

Explain your reasoning – If you disagree

Be grateful – People are spending time to help you

🛠️ Step 9: Tooling Setup
9.1 Recommended VS Code Extensions
Extension Purpose
ESLint JavaScript linting
Prettier Code formatting
GitLens Git history and blame
Thunder Client API testing
Docker Docker support
Tailwind CSS IntelliSense Tailwind support
9.2 VS Code Settings
json

{
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.codeActionsOnSave": {
"source.fixAll.eslint": "explicit"
},
"eslint.validate": [
"javascript",
"javascriptreact",
"typescript",
"typescriptreact"
]
}

9.3 Git Hooks (Husky)

We use Husky to enforce commit standards:
bash

Install husky

npm install -D husky
npx husky install

Add pre-commit hook

npx husky add .husky/pre-commit "npm test"

Add commit-msg hook

npx husky add .husky/commit-msg 'npx commitlint --edit $1'

🌐 Step 10: Community Guidelines
10.1 Code of Conduct

We follow the Contributor Covenant Code of Conduct. Be respectful, inclusive, and kind.
10.2 Communication Channels
Channel Purpose
GitHub Issues Bug reports and feature requests
GitHub Discussions Q&A and community conversations
DEV.to Blog posts and tutorials
Discord (coming soon) Real-time chat
10.3 Issue Reporting

Bug Report Template:
markdown

Description

Brief description of the bug.

Steps to Reproduce

Go to...
Click on...
See error...

Expected Behavior

What should happen.

Actual Behavior

What actually happens.

Environment

OS: Windows/Linux/macOS
Browser: Chrome/Firefox/Safari
Version: v0.4.0

Screenshots (if applicable)

Add screenshots here.

Additional Context

Add any other context here.

Feature Request Template:
markdown

Description

Brief description of the feature.

Use Case

Why is this feature useful?

Proposed Solution

How should it work?

Alternatives

Any alternative solutions?

Additional Context

Add any other context here.

📚 Step 11: Documentation Standards
11.1 README Updates

When adding new features or changing APIs, update the relevant README files:

README.md – Main project overview

gateway/README.md – Gateway documentation

marketplace/README.md – Marketplace documentation

app/README.md – Mobile app documentation

ai-assistant/README.md – AI Assistant documentation

11.2 API Documentation

When adding or changing API endpoints, update:

marketplace/README.md (API section)

docs/api-reference.md (if exists)

11.3 Inline Code Documentation
javascript

/**

Function description
@param {string} param1 - Description of param1
@param {number} param2 - Description of param2
@returns {Promise} Description of return value */ async function myFunction(param1, param2) { // ... }
✅ Step 12: Checklist Before Submitting
```
□

I have tested my changes
□

I have updated the documentation
□

I have added tests for my changes
□

All tests pass locally
□

My code follows the project's style guide
□

My commits follow the Conventional Commits spec
□

I have checked for merge conflicts
□

I have linked relevant issues
□

I have filled in the PR template
□

I am ready for review
```
🐛 Troubleshooting
"Cannot connect to MongoDB"
bash

Check if MongoDB is running

docker ps | grep mongodb

Start MongoDB

docker start mongodb

"Port already in use"
bash

Find and kill process

sudo lsof -i :4000
sudo kill -9 [PID]

Or change port in .env

echo "PORT=4001" >> marketplace/.env

"Tests failing"
bash

Check test output for details

npm test -- --verbose

Run specific test

npm test -- auth.test.js

Update snapshots

npm test -- -u

"Linting errors"
bash

Run linter with auto-fix

npm run lint:fix

Run prettier

npm run format

📋 Quick Reference Card
Command Description
git clone Clone repository
npm install Install dependencies
npm run dev Start development server
npm test Run tests
npm run lint Run linter
npm run format Format code
npm run build Build for production
git checkout -b feature/name Create new branch
git add . Stage changes
git commit -m "feat: message" Commit changes
git push origin branch Push to GitHub
git pull upstream main Pull latest changes
git merge upstream/main Merge upstream changes
📚 Resources
```
MyZubster GitHub: github.com/DanielIoni-creator/myzubster

Contributor Covenant: contributor-covenant.org

Conventional Commits: conventionalcommits.org

Jest Documentation: jestjs.io

ESLint: eslint.org

Prettier: prettier.io
```
🎯 Next Steps
```
Find an issue – Check out open issues

Start small – Look for good-first-issue or help-wanted tags

Ask questions – Use GitHub Discussions

Submit PR – Follow the PR process

Keep contributing – There's always more to do!
```
💬 Join the Community
```
GitHub: github.com/DanielIoni-creator

DEV.to: dev.to/danielioni
```
Built with ❤️ for privacy, freedom, and decentralization.

Happy contributing! 🚀

Clone your fork (replace YOUR_USERNAME)

Add the original repository as upstream

Verify remotes

origin https://github.com/YOUR_USERNAME/myzubster.git (fetch)

origin https://github.com/YOUR_USERNAME/myzubster.git (push)

upstream https://github.com/DanielIoni-creator/myzubster.git (fetch)

upstream https://github.com/DanielIoni-creator/myzubster.git (push)

Clone all submodules recursively

Gateway

Marketplace

AI Assistant (if working on it)

Mobile App (optional)

Gateway

Marketplace

AI Assistant

Using Docker

Or use local MongoDB

Gateway health check

Marketplace health check

AI Assistant

Always create from main

Create feature branch

Run linter

Run linter with auto-fix

Run prettier

Run all tests

Run tests with coverage

Run specific test file

Run tests in watch mode

Pull latest changes

Resolve conflicts if any

Run tests

Run linter

Build the project

Push to your fork

Description

Type of Change

Checklist

Related Issues

Screenshots (if applicable)

Additional Context

Install husky

Add pre-commit hook

Add commit-msg hook

Description

Steps to Reproduce

Expected Behavior

Actual Behavior

Environment

Screenshots (if applicable)

Additional Context

Description

Use Case

Proposed Solution

Alternatives

Additional Context

Check if MongoDB is running

Start MongoDB

Find and kill process

Or change port in .env

Check test output for details

Run specific test

Update snapshots

Run linter with auto-fix

Run prettier