Skip to content

Contributing

Jump to bottom
Dennis Decoene edited this page Dec 28, 2024 · 1 revision

Contributing to Semantic Seed

We love your input! We want to make contributing to Semantic Seed as easy and transparent as possible, whether it's:

  • Reporting a bug
  • Discussing the current state of the code
  • Submitting a fix
  • Proposing new features
  • Improving documentation

Development Process

We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.

Pull Requests

  1. Fork the repo and create your branch from main.
  2. If you've added code that should be tested, add tests.
  3. If you've changed APIs, update the documentation.
  4. Ensure the test suite passes.
  5. Make sure your code lints.
  6. Issue that pull request!

Development Setup

  1. Install dependencies:
yarn install
  1. Start the development server:
yarn dev
  1. Run tests:
yarn test
  1. Lint your code:
yarn lint

Project Structure

src/
  ├── components/       # React components
  │   ├── ui/          # Base UI components
  │   └── ...          # Feature components
  ├── lib/             # Core functionality
  │   ├── WordListManager.ts    # Word list management
  │   └── utils.ts     # Utility functions
  └── data/            # Static data and word lists

Adding New Features

Word Categories

To add or modify word categories:

  1. Update src/lib/categorizedWordlist.ts
  2. Ensure all words are from the official BIP39 wordlist
  3. Add category to the CategoryWordLists type
  4. Update word selection logic if needed
  5. Add tests for the new category

Templates

To add new sentence templates:

  1. Add template to src/components/SentenceTemplate.tsx
  2. Follow existing template structure
  3. Ensure template generates valid BIP39 phrases
  4. Add examples and documentation
  5. Add template tests

UI Components

When adding new UI components:

  1. Use existing UI components from components/ui
  2. Follow the Shadcn/UI pattern
  3. Use Tailwind's core utility classes only
  4. Ensure responsive design
  5. Add component documentation

Code Style

TypeScript

  • Use TypeScript for all new code
  • Define proper interfaces and types
  • Use strict type checking
  • Follow existing type patterns

React

  • Use functional components
  • Implement proper hooks usage
  • Follow React best practices
  • Maintain consistent component structure

CSS/Styling

  • Use Tailwind CSS utilities
  • Never use arbitrary values [mt-[27px]]
  • Follow existing component styling patterns
  • Maintain consistent spacing

Testing

Unit Tests

  • Write tests for new functionality
  • Follow existing test patterns
  • Ensure high coverage
  • Test edge cases

Integration Tests

  • Add integration tests for new features
  • Test component interactions
  • Verify state management
  • Test user workflows

Documentation

Code Documentation

  • Add JSDoc comments for functions
  • Document complex logic
  • Explain non-obvious decisions
  • Keep comments up to date

Wiki Documentation

  • Update relevant wiki pages
  • Add new pages as needed
  • Include examples
  • Keep documentation current

Security

Considerations

  • Maintain air-gapped operation capability
  • Ensure cryptographic security
  • Follow security best practices
  • Document security implications

Reviews

  • Security review for new features
  • Cryptographic review when relevant
  • Document security assumptions
  • Consider threat models

Bug Reports

What to Include

  1. Quick summary and background
  2. Steps to reproduce
  3. Expected behavior
  4. Actual behavior
  5. Notes (possibly including why you think this might be happening)
  6. Screenshots if relevant

Security Issues

  • Do not file public issues for security vulnerabilities
  • Email security team directly
  • Follow responsible disclosure
  • Wait for response before disclosure

Feature Requests

When requesting new features:

  1. Check existing issues first
  2. Describe the feature in detail
  3. Explain the use case
  4. Consider implementation details
  5. Discuss potential drawbacks

Community

Code of Conduct

  • Be respectful and inclusive
  • Follow GitHub community guidelines
  • Maintain professional discourse
  • Help others when possible

Communication

  • Use GitHub issues for bugs
  • Discussions for feature ideas
  • Pull requests for code changes
  • Wiki for documentation

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Clone this wiki locally