241 lines
6.6 KiB
Markdown
241 lines
6.6 KiB
Markdown
# 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](#code-of-conduct)
|
|
- [Getting Started](#getting-started)
|
|
- [Development Setup](#development-setup)
|
|
- [Coding Guidelines](#coding-guidelines)
|
|
- [Workflow](#workflow)
|
|
- [Commit Guidelines](#commit-guidelines)
|
|
- [Pull Request Process](#pull-request-process)
|
|
- [Documentation](#documentation)
|
|
- [What Not to Do](#what-not-to-do)
|
|
|
|
## Code of Conduct
|
|
|
|
By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). 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:
|
|
```bash
|
|
git clone https://git.4nkweb.com/your-username/story-research-zapwall.git
|
|
cd story-research-zapwall
|
|
```
|
|
3. **Add the upstream remote**:
|
|
```bash
|
|
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:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
2. Run linting:
|
|
```bash
|
|
npm run lint
|
|
```
|
|
|
|
3. Run type checking:
|
|
```bash
|
|
npm run type-check
|
|
```
|
|
|
|
4. Start the development server:
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
5. Open [http://localhost:3000](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**:
|
|
```bash
|
|
git checkout main
|
|
git pull upstream main
|
|
```
|
|
|
|
2. **Create a feature branch**:
|
|
```bash
|
|
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](#coding-guidelines)
|
|
2. Test your changes locally
|
|
3. Run lint and type-check:
|
|
```bash
|
|
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**:
|
|
```bash
|
|
git checkout main
|
|
git pull upstream main
|
|
git checkout your-branch-name
|
|
git rebase main
|
|
```
|
|
|
|
2. **Push your changes**:
|
|
```bash
|
|
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/](docs/) directory
|
|
- **Issues**: Search existing issues or create a new one on [Gitea](https://git.4nkweb.com/4nk/story-research-zapwall/issues)
|
|
- **Repository**: [https://git.4nkweb.com/4nk/story-research-zapwall](https://git.4nkweb.com/4nk/story-research-zapwall)
|
|
|
|
Thank you for contributing to zapwall4Science! 🚀
|