Contributing to Pubky

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

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: Protocol and Homeserver
• Pubky Ring: Mobile key manager
• Pubky App: Social application (pubky.app)
• Pubky Nexus: Indexing service
• Pubky CLI: Command-line tool
• PKDNS, Homegate, Pubky Docker: 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
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](/path/to/page/) 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:

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:

// Always specify language
const example = "like this";

Linking:

<!-- Internal -->
[Pubky Core](/explore/pubkycore/introduction/)

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

Admonitions:

:::note
Informational callout.
:::

:::tip
Helpful suggestion.
:::

:::caution
Important warning.
:::

Images:

<!-- 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)

# 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)

# 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)

# 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)

# 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 - 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
2. Search existing issues
3. Read the Troubleshooting 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
2. Follow the spec: Ensure interoperability
3. Test against Nexus: Use nexus.pubky.app
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
• Code: Check project-specific issues
• General: Ask on Telegram

---

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