Skip to content

Contributing

Jump to bottom
aicoder2009 edited this page Jan 29, 2026 · 1 revision

Contributing

Thank you for your interest in contributing to OpenCitation! This project is open source and welcomes contributions from everyone.

Ways to Contribute

Report Bugs

Found a bug? Let us know!

  1. Use the Report Issue button on the website (easiest)
  2. Or open an issue on GitHub

Include:

  • Steps to reproduce the bug
  • Expected behavior
  • Actual behavior
  • Browser and device info
  • Screenshots if helpful

Suggest Features

Have an idea? We'd love to hear it!

  1. Check existing issues to avoid duplicates
  2. Open a new issue with the "Feature Request" label
  3. Describe the feature and why it would be useful

Fix Bugs or Add Features

Want to code? Great!

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Make your changes
  4. Write or update tests
  5. Submit a pull request

Improve Documentation

Documentation improvements are always welcome:

  • Fix typos or unclear explanations
  • Add examples
  • Improve wiki pages
  • Translate documentation

Test and Verify Citations

Help ensure citation accuracy:

  • Test generated citations against official style guides
  • Report any formatting errors
  • Suggest corrections with references to style guides

Development Setup

Prerequisites

  • Node.js 18+
  • npm or yarn
  • Git

Local Setup

# Clone the repository
git clone https://github.com/aicoder2009/opencitation.git
cd opencitation

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your values

# Run development server
npm run dev

Environment Variables

Required for full functionality:

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

# AWS DynamoDB (optional for local dev)
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1

# GitHub Token (for issue reporting)
GITHUB_TOKEN=github_pat_...

Running Tests

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

Code Style

General Guidelines

  • Write clean, readable code
  • Add comments only where logic isn't self-evident
  • Keep functions focused and single-purpose
  • Avoid over-engineering

TypeScript

  • Use TypeScript for all new code
  • Define types for all function parameters and returns
  • Avoid any type when possible

Formatting

  • Use Prettier for code formatting
  • Use ESLint rules (run npm run lint)
  • 2-space indentation
  • Single quotes for strings

Commits

  • Write clear, concise commit messages
  • Use present tense ("Add feature" not "Added feature")
  • Reference issues when applicable (#123)

Project Structure

opencitation/
├── src/
│   ├── app/                 # Next.js app router pages
│   │   ├── api/             # API routes
│   │   ├── cite/            # Citation page
│   │   ├── lists/           # Lists pages
│   │   └── projects/        # Projects pages
│   ├── components/
│   │   └── wiki/            # Wikipedia-style UI components
│   ├── lib/
│   │   ├── citation/        # Citation engine
│   │   │   └── formatters/  # Style formatters (APA, MLA, etc.)
│   │   └── db/              # Database utilities
│   └── types/               # TypeScript types
├── public/                  # Static assets
└── tests/                   # Test files

Pull Request Guidelines

  1. Keep PRs focused - One feature or fix per PR
  2. Write tests - For new features and bug fixes
  3. Update docs - If your change affects documentation
  4. Test locally - Ensure npm run build passes
  5. Describe changes - Explain what and why in the PR description

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Code refactoring

## Testing
How did you test this?

## Screenshots
If applicable

Code of Conduct

  • Be respectful and inclusive
  • Welcome newcomers
  • Focus on constructive feedback
  • No harassment or discrimination

Questions?

License

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

Thank you for helping make OpenCitation better!

Clone this wiki locally