---
title: "Contributing to Pubky"
---

Thank you for your interest in contributing to Pubky! This guide will help you get started.

:::caution[AI-Assisted Contributions]
We welcome contributions made with the help of AI tools, but you are fully responsible for what you submit. You must understand, review, and be able to explain every change in your PR. Unreviewed AI-generated submissions — bulk changes, hallucinated references, or PRs the author cannot explain — will be closed without review.
:::

---

## Ways to Contribute

### 1. Documentation

Help improve this knowledge base:
- Fix typos and errors
- Add missing information
- Improve clarity and explanations
- Add examples and tutorials
- Translate to other languages

### 2. Code Contributions

Contribute to Pubky projects:
- **[Pubky Core](https://pubky.org/explore/pubkycore/introduction.md)**: Protocol and Homeserver
- **[Pubky Ring](https://pubky.org/explore/technologies/pubky-ring.md)**: Mobile key manager
- **[Pubky App](https://pubky.org/explore/pubky-apps/introduction.md)**: Social application ([pubky.app](https://pubky.app))
- **[Pubky Nexus](https://pubky.org/explore/pubky-apps/indexing-and-aggregation/pubky-nexus.md)**: Indexing service
- **[Pubky CLI](https://pubky.org/explore/technologies/pubky-cli.md)**: Command-line tool
- **[PKDNS](https://pubky.org/explore/technologies/pkdns.md)**, **[Homegate](https://pubky.org/explore/technologies/homegate.md)**, **[Pubky Docker](https://pubky.org/explore/technologies/pubky-docker.md)**: Infrastructure tools

### 3. Community Support

Help others in the community:
- Answer questions on Telegram
- Help troubleshoot issues
- Share your projects and experiences
- Write blog posts and tutorials

### 4. Testing & Bug Reports

Improve quality through:
- Testing beta features
- Reporting bugs with detailed reproduction steps
- Suggesting improvements
- Validating fixes

---

## Contributing to Documentation

### Quick Edits

For small fixes (typos, links, formatting):

1. **Fork the repository**: [github.com/pubky/pubky-knowledge-base](https://github.com/pubky/pubky-knowledge-base)
2. **Make your changes**: Edit markdown files in `src/content/docs/`
3. **Submit a pull request**: Include a clear description

### Larger Contributions

For new pages or significant changes:

1. **Discuss first**: Open an issue to discuss your plans
2. **Follow the structure**: Match existing page organization under `src/content/docs/`
3. **Use standard markdown links**: `[Link text](https://pubky.org/path/to/page.md)` for internal links, `[text](url)` for external
4. **Register in sidebar**: If adding a new top-level page, add it to the `sidebar` array in `astro.config.mjs`
5. **Test locally**: Build with Starlight to verify

**Build locally:**
```bash
git clone https://github.com/pubky/pubky-knowledge-base
cd pubky-knowledge-base
npm install
npm run dev
# Visit http://localhost:4321
```

### Documentation Style Guide

**Markdown Conventions:**
- Each page needs a frontmatter block with at least a `title` field
- Use `## Section` for major sections (H2)
- Use `### Subsection` for subsections (H3)
- Use standard markdown links for both internal and external references

**Code Blocks:**
```javascript
// Always specify language
const example = "like this";
```

**Linking:**
```markdown
<!-- Internal -->
[Pubky Core](/explore/pubkycore/introduction/)

<!-- External -->
[Official Docs](https://docs.pubky.org/)
```

**Admonitions:**
```markdown
:::note
Informational callout.
:::

:::tip
Helpful suggestion.
:::

:::caution
Important warning.
:::
```

**Images:**
```markdown
<!-- Always include descriptive alt text -->
![Pubky Core architecture diagram showing homeservers, PKARR, and DHT](/images/pubky-core.svg)
```

---

## Contributing Code

### General Process

1. **Check existing issues**: See if someone is already working on it
2. **Open an issue**: Describe what you want to build/fix
3. **Fork and branch**: Create a feature branch
4. **Write code**: Follow project conventions
5. **Test thoroughly**: Ensure tests pass
6. **Submit PR**: Include description and link to issue

### Code Quality Standards

**All code contributions should:**
- ✅ Pass existing tests
- ✅ Add tests for new features
- ✅ Follow language-specific style guides
- ✅ Include documentation/comments where needed
- ✅ Not introduce new linter warnings
- ✅ Be accompanied by a clear commit message

**Commit Message Format:**
```
type: brief description (max 72 chars)

Longer explanation if needed. Wrap at 72 characters.

Fixes #123
```

**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Code style (formatting, no logic change)
- `refactor`: Code restructuring
- `test`: Adding or updating tests
- `chore`: Maintenance tasks

**Example:**
```
feat: add HTTPS record support to PKDNS

Implements HTTPS DNS record type handling in the PKDNS resolver,
enabling service binding records for modern applications.

Fixes #456
```

---

## Development Setup

### Pubky Core (Rust)

```bash
# Clone
git clone https://github.com/pubky/pubky-core
cd pubky-core

# Build
cargo build

# Run tests
cargo test

# Run homeserver locally
cargo run --bin pubky-homeserver

# Format code
cargo fmt

# Lint
cargo clippy
```

**Requirements:**
- Rust 1.89+

### Pubky Ring (React Native)

```bash
# Clone
git clone https://github.com/pubky/pubky-ring
cd pubky-ring

# Install dependencies
yarn install
cd ios && pod install && cd ..

# Run on iOS
yarn ios

# Run on Android
yarn android

# Run tests
yarn test

# Lint
yarn lint
```

**Requirements:**
- Node.js >= 22.11.0
- Yarn 1.x
- React Native environment (Xcode for iOS, Android Studio for Android)

### Pubky Nexus (Rust)

```bash
# Clone
git clone https://github.com/pubky/pubky-nexus
cd pubky-nexus

# Start dependencies (Neo4j, Redis, PostgreSQL)
cd docker && cp .env-sample .env && docker compose up -d && cd ..

# Build
cargo build

# Run all services
cargo run -p nexusd

# Run API only
cargo run -p nexusd -- api

# Run watcher only
cargo run -p nexusd -- watcher

# Run migrations
cargo run -p nexusd -- db migration run

# Load test data and run tests (requires cargo-nextest)
cargo run -p nexusd -- db mock
cargo nextest run -p nexus-common --no-fail-fast
cargo nextest run -p nexus-webapi --no-fail-fast
cargo nextest run -p nexus-watcher --no-fail-fast
```

**Requirements:**
- Rust
- Docker for databases
- cargo-nextest (`cargo install cargo-nextest`)

### Pubky CLI (Rust)

```bash
# Clone
git clone https://github.com/pubky/pubky-cli
cd pubky-cli

# Build
cargo build

# Install locally
cargo install --path .

# Run tests
cargo test

# Generate completions
pubky-cli tools completions bash > completions.bash
```

---

## Community Guidelines

### Code of Conduct

We expect all contributors to:

- **Be respectful**: Treat everyone with respect and kindness
- **Be collaborative**: Work together constructively
- **Be inclusive**: Welcome diverse perspectives
- **Be professional**: Keep discussions focused and productive
- **Give credit**: Acknowledge others' contributions

### Communication Channels

- **Telegram**: [t.me/pubkycore](https://t.me/pubkycore) - General discussion and support
- **GitHub Issues**: Bug reports and feature requests
- **GitHub Discussions**: Long-form conversations and proposals
- **Pull Requests**: Code review and technical discussion

### Getting Help

**Before asking:**
1. Check the [FAQ](https://pubky.org/faq.md)
2. Search existing issues
3. Read the [Troubleshooting](https://pubky.org/troubleshooting.md) guide
4. Review relevant documentation

**When asking:**
1. Be specific about your problem
2. Include relevant code/logs
3. Mention what you've tried
4. Specify your environment

---

## Review Process

### Documentation PRs

- Reviewed by documentation maintainers
- Usually merged within 1-3 days
- Focus on clarity, accuracy, and consistency

### Code PRs

**Review criteria:**
- Code quality and style
- Test coverage
- Performance implications
- Security considerations
- Breaking changes
- Documentation updates

**Timeline:**
- Initial review: 1-7 days
- Revisions: As needed
- Merge: After approval from maintainer(s)

**Tips for faster review:**
- Keep PRs focused and small
- Include tests
- Update documentation
- Respond to feedback promptly
- Be patient and respectful

---

## Specialized Contributions

### Writing Examples

Share practical examples:

1. **Create a repository**: Your example project
2. **Add to awesome-pubky**: Link to curated list
3. **Write a tutorial**: Blog post or documentation
4. **Record a video**: Screencast or presentation

### Building Clients

Building a Pubky App-compatible client?

1. **Use pubky-app-specs**: [npm package](https://www.npmjs.com/package/pubky-app-specs)
2. **Follow the spec**: Ensure interoperability
3. **Test against Nexus**: Use [nexus.pubky.app](https://nexus.pubky.app/swagger-ui/)
4. **Share your work**: Let the community know!

### Running Infrastructure

Contributing infrastructure:

1. **Public Homeserver**: Host for community use
2. **PKDNS Instance**: Provide DNS resolution
3. **Nexus Instance**: Run custom indexer
4. **PKARR Relay**: Improve network performance

### Translations

Help translate documentation:

1. **Choose a language**: Check what needs translation
2. **Create language folder**: e.g., `/es/` for Spanish
3. **Translate markdown files**: Maintain structure
4. **Submit PR**: Include translation credits

---

## Recognition

### Contributors

All contributors are recognized in:
- Repository README files
- Release notes for significant contributions
- Community shout-outs

### Maintainers

Consistent, high-quality contributors may be invited to become maintainers with:
- Merge permissions
- Release authority
- Architecture input

---

## License

By contributing to Pubky projects, you agree that your contributions will be licensed under the MIT License (or the project's specific license).

**MIT License Basics:**
- ✅ Commercial use allowed
- ✅ Modification allowed
- ✅ Distribution allowed
- ✅ Private use allowed
- ⚠️ No warranty provided

---

## Getting Started Checklist

Ready to contribute? Here's your checklist:

**For Documentation:**
- [ ] Fork pubky-knowledge-base repository
- [ ] Make your changes in `src/content/docs/`
- [ ] Test locally with Starlight (`npm run dev`)
- [ ] Submit pull request

**For Code:**
- [ ] Check project's CONTRIBUTING.md
- [ ] Set up development environment
- [ ] Create feature branch
- [ ] Write code and tests
- [ ] Pass all checks (lint, test, build)
- [ ] Submit pull request

**For Community:**
- [ ] Join Telegram channel
- [ ] Introduce yourself
- [ ] Answer questions where you can
- [ ] Share your projects

---

## Questions?

- **Documentation**: Open an issue on [pubky-knowledge-base](https://github.com/pubky/pubky-knowledge-base/issues)
- **Code**: Check project-specific issues
- **General**: Ask on [Telegram](https://t.me/pubkycore)

---

**Thank you for contributing to Pubky! Together we're building a decentralized, censorship-resistant web. 🚀**