diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..7b2d535a --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,24 @@ +## Description + + +## Related Issue +Closes #ISSUE_NUMBER + +## Type of Change +- [ ] Bug fix +- [ ] New feature +- [ ] Breaking change +- [ ] Documentation update + +## Testing + + +## Screenshots (if applicable) + + +## Checklist +- [ ] I have read the [Contributing Guide](../CONTRIBUTING.md) +- [ ] I have announced my intent to work on this and received approval +- [ ] My code follows the project's code standards +- [ ] I have tested my changes thoroughly +- [ ] I have updated relevant documentation diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..c4c0358a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,325 @@ +# Contributing to Cleanuparr + +Thanks for your interest in contributing to Cleanuparr! This guide will help you get started with development. + +## Before You Start + +### Announce Your Intent + +Before starting any work, please let us know what you want to contribute: + +- For existing issues: Comment on the issue stating you'd like to work on it +- For new features/changes: Create a new issue first and mention that you want to work on it + +This helps us avoid redundant work, git conflicts, and contributions that may not align with the project's direction. + +**Wait for approval from the maintainers before proceeding with your contribution.** + +## Development Setup + +### Prerequisites + +- [.NET 9.0 SDK](https://dotnet.microsoft.com/download/dotnet/9.0) +- [Node.js 18+](https://nodejs.org/) +- [Git](https://git-scm.com/) +- (Optional) [Make](https://www.gnu.org/software/make/) for database migrations +- (Optional) IDE: [JetBrains Rider](https://www.jetbrains.com/rider/) or [Visual Studio](https://visualstudio.microsoft.com/) + +### Repository Setup + +1. Fork the repository on GitHub +2. Clone your fork locally: + ```bash + git clone https://github.com/YOUR_USERNAME/Cleanuparr.git + cd Cleanuparr + ``` +3. Add the upstream repository: + ```bash + git remote add upstream https://github.com/Cleanuparr/Cleanuparr.git + ``` + +## Backend Development + +### Initial Setup + +#### 1. Create a GitHub Personal Access Token (PAT) + +Cleanuparr uses GitHub Packages for NuGet dependencies. You'll need a PAT with `read:packages` permission: + +1. Go to [GitHub Settings > Developer Settings > Personal Access Tokens > Tokens (classic)](https://github.com/settings/tokens) +2. Click "Generate new token" → "Generate new token (classic)" +3. Give it a descriptive name (e.g., "Cleanuparr NuGet Access") +4. Set an expiration (recommend 90 days or longer for development) +5. Select only the `read:packages` scope +6. Click "Generate token" and copy it + +#### 2. Configure NuGet Source + +Add the Cleanuparr NuGet repository: + +```bash +dotnet nuget add source \ + --username YOUR_GITHUB_USERNAME \ + --password YOUR_GITHUB_PAT \ + --store-password-in-clear-text \ + --name Cleanuparr \ + https://nuget.pkg.github.com/Cleanuparr/index.json +``` + +Replace `YOUR_GITHUB_USERNAME` and `YOUR_GITHUB_PAT` with your GitHub username and the PAT you created. + +### Running the Backend + +#### Option 1: Using .NET CLI + +Navigate to the backend directory: +```bash +cd code/backend +``` + +Build the application: +```bash +dotnet build Cleanuparr.Api/Cleanuparr.Api.csproj +``` + +Run the application: +```bash +dotnet run --project Cleanuparr.Api/Cleanuparr.Api.csproj +``` + +Run tests: +```bash +dotnet test +``` + +The API will be available at http://localhost:5000 + +#### Option 2: Using an IDE + +For JetBrains Rider or Visual Studio: +1. Open the solution file: `code/backend/cleanuparr.sln` +2. Set `Cleanuparr.Api` as the startup project +3. Press `F5` to start the application + +### Database Migrations + +Cleanuparr uses two separate database contexts: `DataContext` and `EventsContext`. + +#### Prerequisites + +Install Make if not already installed: +- Windows: Install via [Chocolatey](https://chocolatey.org/) (`choco install make`) or use [WSL](https://docs.microsoft.com/windows/wsl/) +- macOS: Install via Homebrew (`brew install make`) +- Linux: Usually pre-installed, or install via package manager (`apt install make`, `yum install make`, etc.) + +#### Creating Migrations + +From the `code` directory: + +For data migrations (DataContext): +```bash +make migrate-data name=YourMigrationName +``` + +For events migrations (EventsContext): +```bash +make migrate-events name=YourMigrationName +``` + +Example: +```bash +make migrate-data name=AddUserPreferences +make migrate-events name=AddAuditLogEvents +``` + +## Frontend Development + +### Setup + +1. Navigate to the frontend directory: + ```bash + cd code/frontend + ``` + +2. Install dependencies: + ```bash + npm install + ``` + +3. Start the development server: + ```bash + npm start + ``` + +The UI will be available at http://localhost:4200 + +## Documentation Development + +### Setup + +1. Navigate to the docs directory: + ```bash + cd docs + ``` + +2. Install dependencies: + ```bash + npm install + ``` + +3. Start the development server: + ```bash + npm start + ``` + +The documentation site will be available at http://localhost:3000 + +## Building with Docker + +### Building a Local Docker Image + +To build the Docker image locally for testing: + +1. Navigate to the `code` directory: + ```bash + cd code + ``` + +2. Build the image: + ```bash + docker build \ + --build-arg PACKAGES_USERNAME=YOUR_GITHUB_USERNAME \ + --build-arg PACKAGES_PAT=YOUR_GITHUB_PAT \ + -t cleanuparr:local \ + -f Dockerfile . + ``` + + Replace `YOUR_GITHUB_USERNAME` and `YOUR_GITHUB_PAT` with your credentials. + +3. Run the container: + ```bash + docker run -d \ + --name cleanuparr-dev \ + -p 11011:11011 \ + -v /path/to/config:/config \ + -e PUID=1000 \ + -e PGID=1000 \ + -e TZ=Etc/UTC \ + cleanuparr:local + ``` + +4. Access the application at http://localhost:11011 + +### Building for Multiple Architectures + +Use Docker Buildx for multi-platform builds: + +```bash +docker buildx build \ + --platform linux/amd64,linux/arm64 \ + --build-arg PACKAGES_USERNAME=YOUR_GITHUB_USERNAME \ + --build-arg PACKAGES_PAT=YOUR_GITHUB_PAT \ + -t cleanuparr:local \ + -f Dockerfile . +``` + +## Code Standards + +### Backend (.NET/C#) +- Follow existing conventions and [Microsoft C# Coding Conventions](https://docs.microsoft.com/dotnet/csharp/fundamentals/coding-style/coding-conventions) +- Use meaningful variable and method names +- Add XML documentation comments for public APIs +- Write unit tests whenever possible + +### Frontend (Angular/TypeScript) +- Follow existing conventions and the [Angular Style Guide](https://angular.io/guide/styleguide) +- Use TypeScript strict mode +- Write unit tests whenever possible + +### Documentation +- Use clear, concise language +- Include code examples where appropriate +- Update relevant documentation when adding/changing features +- Check for spelling and grammar + +## Submitting Your Contribution + +### 1. Create a Feature Branch + +```bash +git checkout -b feature/your-feature-name +# or +git checkout -b fix/your-bug-fix-name +``` + +### 2. Make Your Changes + +- Write clean, well-documented code +- Follow the code standards outlined above +- **Test your changes thoroughly!** + +### 3. Commit Your Changes + +Write clear, descriptive commit messages: + +```bash +git add . +git commit -m "Add feature: brief description of your changes" +``` + +### 4. Keep Your Branch Updated + +```bash +git fetch upstream +git rebase upstream/main +``` + +### 5. Push to Your Fork + +```bash +git push origin feature/your-feature-name +``` + +### 6. Create a Pull Request + +1. Go to the [Cleanuparr repository](https://github.com/Cleanuparr/Cleanuparr) +2. Click "New Pull Request" +3. Select your fork and branch +4. Fill out the PR template with: + - A descriptive title (e.g., "Add support for Prowlarr integration" or "Fix memory leak in download client polling") + - Description of changes + - Related issue number + - Testing performed + - Screenshots (if applicable) + +### 7. Code Review Process + +- Maintainers will review your PR +- Address any feedback or requested changes +- Once approved, your PR will be merged + +## Other Ways to Contribute + +### Help Test New Features + +We're always looking for testers to help validate new features before they are released. If you'd like to help test upcoming changes: + +1. Join our [Discord community](https://discord.gg/SCtMCgtsc4) +2. Let us know you're interested in testing +3. We'll provide you with pre-release builds and testing instructions + +Your feedback helps us catch issues early and deliver better releases. + +## Getting Help + +- Discord: Join our [Discord community](https://discord.gg/SCtMCgtsc4) for real-time help +- Issues: Check existing [GitHub issues](https://github.com/Cleanuparr/Cleanuparr/issues) or create a new one +- Documentation: Review the [complete documentation](https://cleanuparr.github.io/Cleanuparr/) + +## License + +By contributing to Cleanuparr, you agree that your contributions will be licensed under the same license as the project. + +--- + +Thanks for contributing to Cleanuparr! diff --git a/README.md b/README.md index 30ec0cf2..fcf953a0 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,17 @@ http://localhost:11011 - **💬 [Discord Community](https://discord.gg/SCtMCgtsc4)** - Get help and discuss with other users - **🔗 [GitHub Releases](https://github.com/Cleanuparr/Cleanuparr/releases)** - Download binaries and view changelog +## 🤝 Contributing + +We welcome contributions from the community! Whether it's bug fixes, new features, documentation improvements, or testing, your help is appreciated. + +**Before contributing:** Please read our [Contributing Guide](CONTRIBUTING.md) and announce your intent to work on an issue before starting. + +- **[Contributing Guide](CONTRIBUTING.md)** - Learn how to set up your development environment and submit contributions +- **[Report Issues](https://github.com/Cleanuparr/Cleanuparr/issues/new/choose)** - Found a bug? Let us know! +- **[Feature Requests](https://github.com/Cleanuparr/Cleanuparr/issues/new/choose)** - Share your ideas for new features +- **[Help Test Features](https://discord.gg/SCtMCgtsc4)** - Join Discord to test pre-release features and provide feedback + # Cleanuparr Cleanuparr Huntarr Think of **Cleanuparr** as the janitor of your server; it keeps your download queue spotless, removes clutter, and blocks malicious files. Now imagine combining that with **Huntarr**, the compulsive librarian who finds missing and upgradable media to complete your collection