# Contributing to Pocket
*The contributor guide that doesn't make you want to close the tab immediately*
## Welcome to the Pocket Community
First off, the fact that you're reading a CONTRIBUTING.md file means you're already in the top 1% of humans who might actually help improve this project instead of just complaining about it on Twitter. For that alone, we're grateful.
Contributing to Pocket isn't just about writing code that works—it's about creating a tool that makes developers' lives less frustrating. Because let's be honest, we all have enough existential dread without also having to rewrite the same RegEx pattern for the fifth time this year.
## The Philosophy Behind Pocket
Pocket exists because developers shouldn't have to choose between maintaining an elaborate organizational system that requires more upkeep than a vintage car or randomly scattering useful code across Slack messages, GitHub gists, and hastily-named text files.
When contributing to Pocket, remember we're building a tool that adapts to how developers actually work—chaotic, context-switching, and perpetually convinced they'll "definitely remember" where they put that brilliant piece of code (narrator: they won't).
## Ways to Contribute (All Equally Valuable)
### Code Contributions
Yes, code is the obvious one, but before you start refactoring everything into a single line of undecipherable Rust, consider:
- **Bug fixes**: These are the unsung heroes of open source. Found something broken? Fix it. We promise not to ask why you were using Pocket at 3 AM.
- **Features**: Have an idea that would make Pocket even better at solving the "where did I put that code" problem? Implement it. Just make sure it aligns with our core philosophy of "making it easier to find your stuff without requiring you to be unrealistically organized."
- **Performance improvements**: If you can make Pocket faster without requiring users to sacrifice their firstborn to the Rust compiler, we're interested.
### Documentation
Documentation is like dental floss—everyone knows they should use it more, but nobody wants to do it. That's why documentation contributions are worth their weight in gold (or Bitcoin, if that's still a thing when you're reading this).
Good documentation includes:
- Clear explanations that don't assume the reader has a PhD in Computer Science
- Examples that actually work and aren't just theoretical
- A tone that acknowledges the reader is a human being with limited patience and many browser tabs open
### Bug Reports
Found a bug but don't have time to fix it? No problem. When submitting a bug report, try to include:
- What you were doing when the bug occurred (wrong answers only... kidding, please be accurate)
- What you expected to happen
- What actually happened instead
- Your environment details (OS, Pocket version, whether Mercury is in retrograde)
A good bug report is already halfway to being fixed. A bad bug report is just "it doesn't work" followed by tumbleweeds.
### Feature Requests
Have an idea but not the time or skills to implement it? Share it anyway. The best feature requests:
- Clearly describe the problem you're trying to solve
- Explain why existing features don't quite cut it
- Don't require us to rewrite the entire codebase or violate the laws of physics
## The Technical Stuff
### Setting Up Your Development Environment
1. **Fork & Clone**: Standard GitHub stuff. Fork the repo, clone it locally.
2. **Install Dependencies**: Run `cargo build` and pray to the dependency gods.
3. **Run Tests**: Execute `cargo test` and feel that brief moment of joy when everything passes.
### Code Style & Standards
We use a code style that can best be described as "readable by humans who haven't slept enough." More specifically:
- Run `cargo fmt` before committing. It's automated style enforcement so we don't have to argue about formatting.
- Use meaningful variable names. Future you will thank present you when debugging at midnight.
- Comments should explain why, not what. The code shows what; good comments explain the reasoning that isn't obvious from reading the code.
### The Pull Request Process
1. **Branch Naming**: Use a descriptive name like `feature/amazing-new-thing` or `fix/thing-that-was-horribly-broken`.
2. **Keep PRs Focused**: One feature or fix per PR. We're not looking for a PR that solves all of software engineering's problems at once.
3. **Tests**: Add tests for your changes. Untested code is like an unchaperoned teenager—likely to cause problems when you're not looking.
4. **Documentation**: Update docs to reflect your changes. Yes, all of them.
5. **PR Description**: Explain what your changes do and why they should be merged. "It works on my machine" is not sufficient justification.
### Commit Messages
Good commit messages are like good documentation—rare and precious. We follow these guidelines:
- Start with a verb in the present tense: "Add feature" not "Added feature"
- Keep the first line under 72 characters
- Use the body to explain what and why, not how
For example:
```
Add support for quantum encryption backpacks
This implements a new backpack type that uses quantum encryption to
secure extremely sensitive snippets. Users working with government
secrets or their Netflix password can now store them safely.
Fixes #42
```
## The Human Stuff
### Code of Conduct
We have one rule: Don't be a jerk. This covers most situations, but if you need clarification:
- Treat others with respect and empathy
- Assume good intentions, even when someone's code makes you question their sanity
- Remember that text-based communication lacks tone—that person isn't attacking you, they just forgot to add emojis
- Give constructive feedback, not just criticism
### The Review Process
Your PR will be reviewed by maintainers who are balancing this open source project with day jobs, families, and existential crises about their career choices. Please be patient.
When receiving feedback:
- Don't take it personally
- Ask questions if something isn't clear
- Remember that every suggestion is aimed at making the project better, not criticizing your abilities
## Extension Development
Pocket's extension system is where the real magic happens. When creating extensions:
1. **Do One Thing Well**: The Unix philosophy never goes out of style
2. **Document Extensively**: Assume users haven't read any other documentation
3. **Error Handling**: Users will find ways to break your extension you never imagined
4. **Dependencies**: Keep them minimal and well-justified
## In Conclusion
Contributing to open source is a strange mix of altruism, resume-building, and scratching your own itch. Whatever your motivation, we're glad you're here.
Remember, every contribution—from a typo fix to a major feature—helps make Pocket better for developers everywhere. Each time you contribute, you're saving someone from the special kind of rage that comes from knowing they've solved this exact problem before but can't find the code.
And that, friends, is a genuine service to humanity.
---
*Now go build something awesome. Preferably using Pocket to store all the brilliant code you'll write along the way.*
Thank you for considering contributing to Pocket! This document outlines the process for contributing to the project and how to get started.
## Code of Conduct
By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
## How Can I Contribute?
### Reporting Bugs
Bugs are tracked as GitHub issues. Create an issue and provide the following information:
- Use a clear and descriptive title
- Describe the exact steps to reproduce the problem
- Provide specific examples to demonstrate the steps
- Describe the behavior you observed after following the steps
- Explain which behavior you expected to see instead and why
- Include screenshots if possible
### Suggesting Enhancements
Enhancement suggestions are also tracked as GitHub issues. When creating an enhancement suggestion:
- Use a clear and descriptive title
- Provide a detailed description of the suggested enhancement
- Explain why this enhancement would be useful to most Pocket users
- Provide examples of how it would be used
### Pull Requests
- Fill in the required template
- Follow the Rust style guide
- Include tests for new features or bug fixes
- Update documentation as needed
- End all files with a newline
## Development Workflow
### Setting Up the Development Environment
1. Fork the repository
2. Clone your fork: `git clone https://github.com/frgmt0/pocket.git`
3. Add the upstream repository: `git remote add upstream https://github.com/frgmt0/pocket.git`
4. Install dependencies: `cargo build`
### Making Changes
1. Create a new branch: `git checkout -b your-branch-name`
2. Make your changes
3. Run tests: `cargo test`
4. Run the linter: `cargo clippy`
5. Format your code: `cargo fmt`
6. Commit your changes with a descriptive message
7. Push to your fork: `git push origin your-branch-name`
8. Create a pull request
### Versioning
Pocket uses a letter-based versioning system:
- Format: `v-pocket-XN[-nc]`
- `X` is a letter indicating stability:
- `A` = Alpha (experimental, seeking feedback)
- `B` = Beta (still buggy but usable for testing)
- `C` = Candidate (almost ready for official release)
- `R` = Release (stable and ready for production)
- `N` is a number indicating the iteration
- `-nc` (optional) indicates compatibility issues with previous versions
## Project Structure
```
pocket/
├── .github/ # GitHub configuration files
├── src/ # Source code
│ ├── commands/ # Command implementations
│ ├── models/ # Data models
│ ├── search/ # Search functionality
│ ├── storage/ # Storage management
│ ├── utils/ # Utility functions
│ ├── version.rs # Version information
│ └── main.rs # Entry point
├── Cargo.toml # Project configuration
└── README.md # Project documentation
```
## Testing
- Run all tests: `cargo test`
- Run specific tests: `cargo test test_name`
- Run with coverage: `cargo tarpaulin`
## Documentation
- Update the README.md for user-facing changes
- Document code with rustdoc comments
- Update CHANGELOG.md for new releases
## Questions?
If you have any questions, feel free to create an issue or reach out to me.
Thank you for contributing to Pocket!