Kavita/CONTRIBUTING.md

How to Contribute

We're always looking for people to help make Kavita even better, there are a number of ways to contribute.

Contribute to the Wiki

Our documentation is a community effort! You can fix a typo, clarify a setup step, or add a new FAQ to the wiki. The more information we have on the wiki the better.

The docs are maintained in the Wiki-Nextra repository.

Getting Started: Development Setup

Tools required

• .NET editor
  • Rider (preferred)
  • Visual Studio 2019 or higher
• HTML/Javascript editor (VS Code/Sublime Text/Webstorm/Atom/etc)
• Git
• NodeJS (Node 18.13.X or higher)
• .NET 9.0+
• dotnet tool install -g Swashbuckle.AspNetCore.Cli
• dotnet cli tools link

Fork and Clone Kavita

Fork the repository on GitHub, then clone your fork onto your local development machine.

Frontend

1. Install the required Node Packages
   • cd Kavita/UI/Web
   • npm install
   • npm install -g @angular/cli
2. Start the frontend
   • npm run start
3. Open http://localhost:4200

Debugging on Device

Run npm run start-proxy instead to have the Angular application proxy the requests to the backend.

Backend

1. Build the project in Visual Studio/Rider, and set the startup project to Kavita.Server (Server)
2. Debug the project in Visual Studio/Rider

Troubleshooting for Apple users

The backend may fail to start due to port 5000 already being in use. To fix this, temporarily turn off AirPlay Receiver in System Settings.

You can re-enable the setting later, and it will bind to a different port. You may need to do this again after an update or reboot.

Deployment

Run build.sh and pass the Runtime Identifier for your OS or just build.sh for all supported RIDs.

Database Changes

• When you need to make changes to the Db, update the Entities then run: dotnet ef migrations add --project Kavita.Database\Kavita.Database.csproj --startup-project Kavita.Server\Kavita.Server.csproj --context Kavita.Database.DataContext --configuration Debug --output-dir Migrations MeaningfulName

Contributing Code

General Guidelines

• If you're working on a requested feature, please comment on the Github Issue so work is not duplicated
• If you want to add something without an existing issue, please talk to us first or open an issue
• Rebase from Kavita's develop branch, don't merge
• Make meaningful commits, or squash them
• Add tests (unit/integration)
• Reach out to us on Discord if you have any questions

Formatting

• Commit with *nix line endings for consistency (We checkout Windows and commit *nix)
• Use 4 spaces instead of tabs, this is the default for VS 2019 and WebStorm (to our knowledge)
• Use 2 spaces for UI files

Pull Requests

Feel free to make a pull request before work is complete, this will let us see where it's at and make comments/suggest improvements.

1. Use feature branches to develop

Each PR should come from its own feature branch (not develop in your fork). It should have a meaningful branch name to describe what is being added/fixed.

Great Example	Bad Example
feature/parser-enhancements	new-feature
bugfix/sidenav-mobile-overlap	fix-bug
docs/contributing	contributiondocs

2. Don't submit large pull requests

Make sure there is only one feature/bug fix per pull request to keep things clean and easy to understand.

3. Only make pull requests to develop

If you make a PR to main we'll comment on it and close it.

4. Review our comments or questions

We review each PR for consistency and maintainability. We'll try to respond as soon as possible. If it's been a day or two, please reach out to us, we may have missed it.

API Reference (Swagger)

To view the full API documentation and test endpoints locally, run the server in Debug mode.

1. Navigate to server directory: cd Kavita/Kavita.Server
2. Start server: dotnet run -c Debug
3. Access the UI at: http://localhost:5000/swagger/index.html

For any build issues run swagger tofile --output ../openapi.json API/bin/Debug/net8.0/API.dll v1 to see the error and correct it.

Building external scripts/apps

We welcome anyone to build external scripts and applications. Reach out to us about publishing, we will link it from our wiki and Discord.

Please do not use words like "Kavita reader" or "Kavita" as your explicit app name. Use of "[name]: A Kavita Reader" is preferred.

If you have any questions about any of this, please let us know.