story-research-zapwall/CONTRIBUTING.md

Contributing to zapwall4Science

Thank you for your interest in contributing to zapwall4Science! This document provides guidelines and instructions for contributing to the project.

Table of Contents

• Code of Conduct
• Getting Started
• Development Setup
• Coding Guidelines
• Workflow
• Commit Guidelines
• Pull Request Process
• Documentation
• What Not to Do

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct. We are committed to providing a welcoming and inclusive environment for all contributors.

Getting Started

1. Fork the repository on Gitea
2. Clone your fork locally:

   git clone https://git.4nkweb.com/your-username/story-research-zapwall.git
   cd story-research-zapwall
   

3. Add the upstream remote:

   git remote add upstream https://git.4nkweb.com/4nk/story-research-zapwall.git
   

Development Setup

Prerequisites

• Node.js: 18 or higher
• npm: Latest version
• Alby browser extension: For testing Nostr authentication and Lightning payments

Installation

1. Install dependencies:

   npm install
   

2. Run linting:

   npm run lint
   

3. Run type checking:

   npm run type-check
   

4. Start the development server:

   npm run dev
   

5. Open http://localhost:3000 in your browser

Coding Guidelines

Core Principles

• No fallbacks or silent failures: All errors must be explicitly handled and logged
• No analytics: Analytics are not allowed in this project
• No tests unless explicitly requested: Do not add ad-hoc tests
• Strict TypeScript: Respect lint, type-check, accessibility, and exactOptionalPropertyTypes
• No shortcuts: No ts-ignore, no untyped any, no console.log if a logger exists

Code Quality

• Split large components/functions: Stay within lint limits (max-lines, max-lines-per-function)
• Prefer typed helpers/hooks: Avoid duplication, reuse existing utilities
• Error handling: Errors must surface with clear messages; do not swallow exceptions
• Storage: Use IndexedDB encrypted (AES-GCM) via lib/storage/cryptoHelpers.ts
• Nostr: Use lib/articleMutations.ts and lib/nostr*.ts helpers; no direct fallbacks

TypeScript Standards

• Full type coverage: No any types without explicit justification
• No type assertions: Avoid as casts unless absolutely necessary
• Strict mode: All TypeScript strict checks must pass
• No @ts-ignore or @ts-nocheck: Fix type issues properly

Accessibility

• ARIA: Proper ARIA labels and roles
• Keyboard navigation: All interactive elements must be keyboard accessible
• Contrast: Meet WCAG contrast requirements
• No regressions: Maintain or improve accessibility with each change

Workflow

Creating a Branch

1. Update your fork:

   git checkout main
   git pull upstream main
   

2. Create a feature branch:

   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/your-bug-fix
   

Making Changes

1. Make your changes following the coding guidelines
2. Test your changes locally
3. Run lint and type-check:

   npm run lint
   npm run type-check
   

Before Submitting

• Code follows the project's coding guidelines
• Lint passes (npm run lint)
• Type-check passes (npm run type-check)
• No console.log statements (use logger if available)
• Errors are properly handled and logged
• Accessibility requirements are met
• Documentation is updated if needed

Commit Guidelines

Commit Message Format

Commits should be exhaustive and synthetic with the following structure:

**Motivations:**
- Reason for the change

**Root causes:**
- Underlying issue (if applicable)

**Correctifs:**
- What was fixed

**Evolutions:**
- New features or improvements

**Pages affectées:**
- Files or components modified

Example

Fix payment modal not closing after successful payment

**Motivations:**
- Users reported payment modal staying open after successful payment

**Root causes:**
- Missing state update after payment confirmation

**Correctifs:**
- Added state reset in payment success handler
- Added cleanup in useEffect hook

**Evolutions:**
- Improved user experience with automatic modal closure

**Pages affectées:**
- components/PaymentModal.tsx
- hooks/useArticlePayment.ts

Pull Request Process

1. Update your branch:

   git checkout main
   git pull upstream main
   git checkout your-branch-name
   git rebase main
   

2. Push your changes:

   git push origin your-branch-name
   

3. Create a Pull Request on Gitea:

   • Use a clear, descriptive title
   • Fill out the PR template completely
   • Reference any related issues
   • Add screenshots if UI changes are involved

4. Wait for review: Maintainers will review your PR and provide feedback

5. Address feedback: Make requested changes and push updates to your branch

6. Documentation:

   • Document fixes in fixKnowledge/ directory
   • Document features in features/ directory

Documentation

When to Document

• Fixes: Document in fixKnowledge/ with problem, impacts, root cause, corrections, modifications, deployment, and analysis procedures
• Features: Document in features/ with objective, impacts, modifications, deployment, and analysis procedures

Documentation Format

Follow the existing documentation structure:

• Clear sections with headers
• Code examples where relevant
• Links to related documentation
• Author attribution (Équipe 4NK)

What Not to Do

• ❌ No analytics: Do not add analytics tracking
• ❌ No ad-hoc tests: Do not add tests unless explicitly requested
• ❌ No environment overrides: Do not override environment variables
• ❌ No silent retry/fallback: All failures must be explicit
• ❌ No shortcuts: No ts-ignore, no any, no console.log
• ❌ No breaking changes: Maintain backward compatibility unless explicitly required

Getting Help

• Documentation: Check the docs/ directory
• Issues: Search existing issues or create a new one on Gitea
• Repository: https://git.4nkweb.com/4nk/story-research-zapwall

Thank you for contributing to zapwall4Science! 🚀