mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-02-08 05:56:45 +00:00
deploy test
This commit is contained in:
miloschwartz
218
development/contributing.mdx
Normal file
218
development/contributing.mdx
Normal file
@@ -0,0 +1,218 @@
|
||||
---
|
||||
title: "Development Guide"
|
||||
description: "Set up your local development environment for contributing to Pangolin"
|
||||
---
|
||||
|
||||
This guide describes how to set up your local development environment for contributing to Pangolin. We recommend using Docker Compose for the most consistent development experience across different environments.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<Check>
|
||||
- Text Editor (VSCode, Neovim, etc.)
|
||||
- NodeJS v20.10.0
|
||||
- NPM v10.2.3 (or similar)
|
||||
- Go v1.23.1
|
||||
- Git
|
||||
- Docker & Docker Compose
|
||||
</Check>
|
||||
|
||||
<Info>
|
||||
For managing multiple versions of Go, you may want to use [gvm](https://github.com/moovweb/gvm).
|
||||
For managing multiple versions of NodeJS, you may want to use [nvm](https://github.com/nvm-sh/nvm).
|
||||
</Info>
|
||||
|
||||
## Setup Your Repository
|
||||
|
||||
Below is an example if you're working on the Pangolin repository.
|
||||
|
||||
<Steps>
|
||||
<Step title="Fork and clone">
|
||||
[Fork](https://help.github.com/articles/fork-a-repo/) the repository(ies) to your own GitHub account and [clone](https://help.github.com/articles/cloning-a-repository/) to your local device:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/YOUR_USERNAME/pangolin.git
|
||||
cd pangolin/
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Add upstream remote">
|
||||
Add the remote `upstream`:
|
||||
|
||||
```bash
|
||||
git remote add upstream https://github.com/fosrl/pangolin.git
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Create feature branch">
|
||||
Create a new branch:
|
||||
|
||||
```bash
|
||||
git checkout -b BRANCH_NAME dev
|
||||
```
|
||||
|
||||
<Tip>
|
||||
It is recommended to give your branch a meaningful name, relevant to the feature or fix you are working on.
|
||||
|
||||
**Good examples**:
|
||||
- `docs-docker`
|
||||
- `feature-new-system`
|
||||
- `fix-title-cards`
|
||||
|
||||
**Bad examples**:
|
||||
- `bug`
|
||||
- `docs`
|
||||
- `feature`
|
||||
- `fix`
|
||||
- `patch`
|
||||
</Tip>
|
||||
</Step>
|
||||
|
||||
<Step title="Open pull request">
|
||||
If you open a pull request, open it against the `dev` branch of the original repository.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Pangolin Development Setup
|
||||
|
||||
### Option 1: Docker Compose (Recommended)
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Advantages" icon="check">
|
||||
- Consistent environment
|
||||
- Easy setup and teardown
|
||||
- Isolated dependencies
|
||||
- Works on any OS
|
||||
</Card>
|
||||
|
||||
<Card title="Requirements" icon="docker">
|
||||
- Docker installed
|
||||
- Docker Compose installed
|
||||
- 4GB+ RAM available
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Steps>
|
||||
<Step title="Install dependencies">
|
||||
Install package dependencies:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Configure environment">
|
||||
Ensure you have a `config/` directory at the root with a `config.yml` inside. Refer to the [Pangolin Configuration docs](/self-host/advanced/config-file) or the `config.example.yml` in the repo for a sample of what to include in that file.
|
||||
|
||||
<Warning>
|
||||
You may need to tweak this to run in dev, such as setting the `dashboard_url` to `http://localhost:3002`.
|
||||
</Warning>
|
||||
</Step>
|
||||
|
||||
<Step title="Generate database schema">
|
||||
Generate the database schema and push it:
|
||||
|
||||
```bash
|
||||
npm run db:sqlite:generate
|
||||
npm run db:sqlite:push
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Start development server">
|
||||
Start the development server using Docker Compose:
|
||||
|
||||
```bash
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
<Tip>
|
||||
This will build and start all services in development mode with hot reloading enabled.
|
||||
</Tip>
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
When running Pangolin for the first time there will be no exit nodes. This means that there have been no Gerbil "exit nodes" registered in the database. When Gerbil first starts up and requests its config from Pangolin for the first time it gets registered as an exit node.
|
||||
|
||||
The easiest way to resolve this is to run Gerbil and have it register in your dev environment. Download the Gerbil binary and run it with localhost:
|
||||
|
||||
```bash
|
||||
./gerbil \
|
||||
--remoteConfig http://localhost:3001/api/v1/gerbil/get-config \
|
||||
--reportBandwidthTo http://localhost:3001/api/v1/gerbil/receive-bandwidth \
|
||||
--generateAndSaveKeyTo=/var/key \
|
||||
--reachableAt=http://localhost:3003
|
||||
```
|
||||
</Note>
|
||||
|
||||
### Option 2: Local Development
|
||||
|
||||
<Warning>
|
||||
Local development requires more setup and may have environment-specific issues. Docker Compose is recommended for consistency.
|
||||
</Warning>
|
||||
|
||||
<Steps>
|
||||
<Step title="Install dependencies">
|
||||
Install package dependencies:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Configure environment">
|
||||
Ensure you have a `config/` directory at the root with a `config.yml` inside. Refer to the [Pangolin Configuration docs](/self-host/advanced/config-file) or the `config.example.yml` in the repo for a sample of what to include in that file.
|
||||
|
||||
<Warning>
|
||||
You may need to tweak this to run in dev, such as setting the `dashboard_url` to `http://localhost:3002`.
|
||||
</Warning>
|
||||
</Step>
|
||||
|
||||
<Step title="Generate database schema">
|
||||
Generate the database schema and push it:
|
||||
|
||||
```bash
|
||||
npm run db:sqlite:generate
|
||||
npm run db:sqlite:push
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Start development server">
|
||||
Start the development server:
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Component Development
|
||||
|
||||
### Gerbil
|
||||
|
||||
<Card title="Requirements">
|
||||
- Go v1.23.1
|
||||
</Card>
|
||||
|
||||
```bash
|
||||
make local
|
||||
```
|
||||
|
||||
### Newt
|
||||
|
||||
<Card title="Requirements">
|
||||
- Go v1.23.1
|
||||
</Card>
|
||||
|
||||
```bash
|
||||
make local
|
||||
```
|
||||
|
||||
### Olm
|
||||
|
||||
<Card title="Requirements">
|
||||
- Go v1.23.1
|
||||
</Card>
|
||||
|
||||
```bash
|
||||
make local
|
||||
```
|
||||
176
development/feature-requests-and-bug-reports.mdx
Normal file
176
development/feature-requests-and-bug-reports.mdx
Normal file
@@ -0,0 +1,176 @@
|
||||
---
|
||||
title: "Feature Requests & Bug Reports"
|
||||
description: "How to submit feature requests and report bugs for Pangolin"
|
||||
---
|
||||
|
||||
We welcome contributions from the community to help improve Pangolin. To ensure your feedback is properly tracked and prioritized, please use the appropriate GitHub sections for different types of submissions.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Feature Requests" icon="lightbulb">
|
||||
Submit in GitHub Discussions for community feedback and upvoting
|
||||
</Card>
|
||||
|
||||
<Card title="Bug Reports" icon="bug">
|
||||
Submit in GitHub Issues for tracking and resolution
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Feature Requests
|
||||
|
||||
<Info>
|
||||
**Use GitHub Discussions**: [Pangolin Discussions](https://github.com/fosrl/pangolin/discussions)
|
||||
</Info>
|
||||
|
||||
We encourage you to submit feature requests in the [GitHub Discussions section](https://github.com/fosrl/pangolin/discussions) of the Pangolin repository. This allows the community to:
|
||||
|
||||
- **Upvote features** they want to see implemented
|
||||
- **Provide feedback** and suggestions on proposed features
|
||||
- **Discuss implementation details** and alternatives
|
||||
- **Help prioritize** which features to work on next
|
||||
|
||||
### How to Submit a Feature Request
|
||||
|
||||
<Steps>
|
||||
<Step title="Check existing discussions">
|
||||
Search the [Discussions section](https://github.com/fosrl/pangolin/discussions) to see if your feature has already been requested.
|
||||
</Step>
|
||||
|
||||
<Step title="Create a new discussion">
|
||||
Click "New discussion" and select "Feature Requests" or "Ideas" as the category.
|
||||
</Step>
|
||||
|
||||
<Step title="Provide details">
|
||||
Include:
|
||||
- Clear description of the feature
|
||||
- Use case and benefits
|
||||
- Any implementation ideas
|
||||
- Screenshots or mockups if applicable
|
||||
</Step>
|
||||
|
||||
<Step title="Engage with community">
|
||||
Respond to comments and help refine the feature proposal.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Feature Request Template
|
||||
|
||||
```markdown
|
||||
## Feature Request: [Brief Description]
|
||||
|
||||
### What problem does this solve?
|
||||
[Describe the problem or limitation this feature would address]
|
||||
|
||||
### Proposed solution
|
||||
[Describe how this feature would work]
|
||||
|
||||
### Use cases
|
||||
[Describe specific scenarios where this would be useful]
|
||||
|
||||
### Additional context
|
||||
[Any other relevant information, screenshots, or examples]
|
||||
```
|
||||
|
||||
<Note>
|
||||
Feature requests with community support (upvotes and positive feedback) are more likely to be prioritized for development.
|
||||
</Note>
|
||||
|
||||
## Bug Reports
|
||||
|
||||
<Warning>
|
||||
**Use GitHub Issues**: [Pangolin Issues](https://github.com/fosrl/pangolin/issues)
|
||||
</Warning>
|
||||
|
||||
Bug reports should be submitted in the [GitHub Issues section](https://github.com/fosrl/pangolin/issues) for proper tracking and resolution. This ensures:
|
||||
|
||||
- **Proper tracking** of bugs through their lifecycle
|
||||
- **Developer visibility** for quick resolution
|
||||
- **Version tracking** and regression testing
|
||||
- **Duplicate detection** and consolidation
|
||||
|
||||
### How to Submit a Bug Report
|
||||
|
||||
<Steps>
|
||||
<Step title="Check existing issues">
|
||||
Search the [Issues section](https://github.com/fosrl/pangolin/issues) to see if the bug has already been reported.
|
||||
</Step>
|
||||
|
||||
<Step title="Create a new issue">
|
||||
Click "New issue" and select "Bug report" as the template.
|
||||
</Step>
|
||||
|
||||
<Step title="Fill out the template">
|
||||
Provide all requested information including:
|
||||
- Steps to reproduce
|
||||
- Expected vs actual behavior
|
||||
- Environment details
|
||||
- Error messages or logs
|
||||
</Step>
|
||||
|
||||
<Step title="Add labels">
|
||||
Use appropriate labels to help categorize the issue.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Bug Report Template
|
||||
|
||||
```markdown
|
||||
## Bug Description
|
||||
[Brief description of the bug]
|
||||
|
||||
## Steps to Reproduce
|
||||
1. [First step]
|
||||
2. [Second step]
|
||||
3. [Third step]
|
||||
|
||||
## Expected Behavior
|
||||
[What should happen]
|
||||
|
||||
## Actual Behavior
|
||||
[What actually happens]
|
||||
|
||||
## Environment
|
||||
- **Pangolin Version**: [version]
|
||||
- **OS**: [operating system]
|
||||
- **Browser**: [if applicable]
|
||||
- **Docker Version**: [if using Docker]
|
||||
|
||||
## Error Messages
|
||||
[Any error messages or logs]
|
||||
|
||||
## Additional Context
|
||||
[Screenshots, configuration files, or other relevant information]
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Please provide as much detail as possible to help developers reproduce and fix the issue quickly.
|
||||
</Warning>
|
||||
|
||||
## Before Submitting
|
||||
|
||||
<Check>
|
||||
- Search existing discussions and issues to avoid duplicates
|
||||
- Provide clear, detailed information
|
||||
- Include steps to reproduce (for bugs)
|
||||
- Test on the latest version of Pangolin
|
||||
- Check if the issue is environment-specific
|
||||
</Check>
|
||||
|
||||
## Alternative Channels
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Security Issues" icon="shield">
|
||||
For security vulnerabilities, please email security@fossorial.com instead of posting publicly.
|
||||
</Card>
|
||||
|
||||
<Card title="General Questions" icon="question">
|
||||
For general questions, use [GitHub Discussions](https://github.com/fosrl/pangolin/discussions) with the "Q&A" category, or come chat with us on [Discord](https://discord.gg/HCJR8Xhme4).
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Contributing Code
|
||||
|
||||
If you'd like to implement a feature or fix a bug yourself, please see our [Development Guide](/development/contributing) for setup instructions and coding guidelines.
|
||||
|
||||
<Note>
|
||||
We appreciate all contributions, whether they're feature requests, bug reports, or code contributions. Your feedback helps make Pangolin better for everyone.
|
||||
</Note>
|
||||
Reference in New Issue
Block a user