Contributing Guidelines

​

Welcome Contributors

​

Code of Conduct

• Be respectful and inclusive
• Focus on what’s best for the community
• Show empathy towards other contributors
• Accept constructive criticism gracefully
• Prioritize clinical accuracy and user privacy

​

How to Contribute

​

Reporting Bugs

​

Suggesting Features

• Align with the project’s privacy-first philosophy
• Maintain clinical accuracy of the instrument
• Improve accessibility or user experience
• Be described clearly with use cases

​

Submitting Code Changes

git clone https://github.com/yourusername/raads-r-self-host.git
cd raads-r-self-host
npm install

git checkout -b feature/your-feature-name

npm run test        # Run all tests
npm run lint        # Check code quality
npm run build       # Ensure it builds
npm run dev         # Manual testing

git commit -m "fix: correct reverse scoring for normative items"

git push origin feature/your-feature-name

​

Development Standards

​

Code Quality

• TypeScript: Use strict typing, avoid any
• Components: Keep components focused and single-purpose
• Hooks: Extract reusable logic into custom hooks
• Accessibility: Maintain WCAG 2.1 AA compliance
• Performance: Avoid unnecessary re-renders and computations

interface Props {
  score: number;
  maxScore: number;
}

function ScoreDisplay({ score, maxScore }: Props) {
  const percentage = Math.round((score / maxScore) * 100)
  return <span>{percentage}%</span>
}

​

Testing Requirements

• Unit Tests: Test individual functions and logic
• Integration Tests: Test component interactions
• Golden Tests: Validate against known correct outputs

import { describe, it, expect } from 'vitest'
import { yourFunction } from '../your-module'

describe('yourFunction', () => {
  it('should handle normal case', () => {
    expect(yourFunction(input)).toBe(expectedOutput)
  })
  
  it('should handle edge case', () => {
    expect(yourFunction(edgeInput)).toBe(edgeOutput)
  })
})

npm run test

​

Documentation

• Code Comments: Explain “why” not “what”
• JSDoc: Add for public functions
• README Updates: For feature additions
• Type Definitions: Keep TypeScript types accurate

/**
 * Calculates domain scores with reverse scoring for normative items.
 * 
 * @param responses - User responses (0-3) keyed by item ID
 * @param dataset - Complete questionnaire dataset
 * @returns Calculated results with domain and total scores
 */
export function calculateResults(
  responses: Responses,
  dataset: Dataset
): Results {
  // Implementation
}

​

Clinical Accuracy Guidelines

​

Scoring Logic

• Cross-reference with the original RAADS-R paper
• Validate against golden test vectors
• Ensure both scoring engines (scoring.ts and scoring-alt.ts) remain synchronized
• Document the clinical justification

​

Question Text

• Preserve the exact clinical wording from the published instrument
• Any modifications should be clearly documented and justified
• Update tests to reflect changes

​

Thresholds

• Only modify based on validated research
• Include citations in your PR description
• Update documentation to explain the change

​

Privacy & Security

• Never add external API calls (except for static file serving)
• Never add tracking or analytics
• Never add cookies (beyond optional localStorage)
• Keep all data client-side
• Maintain opt-in consent for any data persistence

​

Pull Request Checklist

• Code follows existing style and conventions
• All tests pass (npm run test)
• No linting errors (npm run lint)
• Production build works (npm run build)
• Changes are documented (code comments, README, etc.)
• Commit messages are clear and descriptive
• PR description explains the change and why it’s needed
• Screenshots included for UI changes
• No breaking changes (or clearly documented if necessary)
• Privacy principles maintained (no tracking, no external calls)

​

Review Process

​

Getting Help

• Documentation: Check the Development Setup and Project Structure guides
• Questions: Open a GitHub issue with the “question” label
• Discussion: Start a discussion in GitHub Discussions

​

Licence

​

Attribution

​

Next Steps

• Set up your Local Development Environment
• Understand the Project Structure
• Learn about Customization Options