⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
chore: enhance contributing guidelines and README for clarity and accessibility
Andrejadf35fbacdd2
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 8720c2fd2..8ec9ca9a1 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -1,108 +1,155 @@# Contributing to Kaneo-Thank you for your interest in contributing to Kaneo! All kinds of contributions are valuable to us. This guide will help you get started with the contribution process.+Thanks for wanting to contribute to Kaneo! Whether you're fixing bugs, adding features, or improving docs, we appreciate your help.## Table of Contents- [Code of Conduct](#code-of-conduct)- [Getting Started](#getting-started)- - [Requirements](#requirements)- - [Local Development Setup](#local-development-setup)-- [Making Contributions](#making-contributions)- - [Finding Issues to Work On](#finding-issues-to-work-on)- - [Creating Pull Requests](#creating-pull-requests)+ - [What You'll Need](#what-youll-need)+ - [Setting Up Your Dev Environment](#setting-up-your-dev-environment)+- [Making Your First Contribution](#making-your-first-contribution)+ - [Finding Something to Work On](#finding-something-to-work-on)+ - [The Process](#the-process)- [Development Guidelines](#development-guidelines)- [Code Style](#code-style)- - [Conventional Commits](#conventional-commits)+ - [Commit Messages](#commit-messages)- [Project Structure](#project-structure)+ - [Testing](#testing)- [Need Help?](#need-help)## Code of Conduct-We are a community-driven project and we expect all contributors to follow our Code of Conduct. Please read it before participating. [Code of Conduct](https://www.contributor-covenant.org/version/2/0/code_of_conduct/)+We want everyone to feel welcome here. Please be respectful and follow our [Code of Conduct](https://www.contributor-covenant.org/version/2/0/code_of_conduct/).## Getting Started-### Requirements+### What You'll Need-- Docker-- Docker Compose-- Git+- **Node.js** (18 or newer)+- **pnpm** (we use this instead of npm/yarn)+- **Git**+- **Docker** (optional, for testing full deployments)-### Local Development Setup--1. Fork and clone the repository:+### Setting Up Your Dev Environment+1. **Fork and clone the repo**:```bash-git clone https://github.com/usekaneo/kaneo.git+git clone https://github.com/yourusername/kaneo.git+cd kaneo```-2. Install the dependencies:-+2. **Install dependencies**:```bash-bun install+pnpm install```-3. Add JWT_ACCESS environment variable:-+3. **Set up environment variables**:```bash-echo "JWT_ACCESS=<token>" > apps/api/.env+# Create a .env file in the API directory+echo "JWT_ACCESS=your-development-secret-here" > apps/api/.env```-4. Start the development server:-+4. **Start everything up**:```bash-bun run dev+pnpm run dev```-This will start the frontend and backend servers on [http://localhost:5173](http://localhost:5173) and [http://localhost:1337](http://localhost:1337) respectively.+This starts both the API (port 1337) and web app (port 5173). Both will automatically reload when you make changes.-## Making Contributions+> **Tip**: The web app at http://localhost:5173 will automatically connect to the API at http://localhost:1337-### Finding Issues to Work On+## Making Your First Contribution-- Check the [issues](https://github.com/usekaneo/kaneo/issues) page for open issues.-- Check the [Discord server](https://discord.gg/rU4tSyhXXU) for help with issues.+### Finding Something to Work On-### Creating Pull Requests+- **Browse [open issues](https://github.com/usekaneo/kaneo/issues)** - look for "good first issue" labels+- **Check our [Discord](https://discord.gg/rU4tSyhXXU)** - we often discuss features and bugs there+- **Found a bug?** Feel free to fix it and open a PR-- Create a new branch for your changes.-- Make your changes and commit them using conventional commits:+### The Process+1. **Create a branch** for your work:```bash-git commit -m "feat: add new feature"+git checkout -b fix/whatever-youre-fixing+# or+git checkout -b feat/cool-new-feature```-- Push your changes to your fork.+2. **Make your changes** and test them locally+3. **Commit using conventional commits**:```bash-git push origin my-branch+git commit -m "fix: resolve calendar date selection bug"+git commit -m "feat: add bulk task operations"+git commit -m "docs: update deployment guide"```-- Create a pull request.+4. **Push and create a PR**:+```bash+git push origin your-branch-name+```++Then open a pull request on GitHub with a clear description of what you changed and why.## Development Guidelines### Code Style-- Use `biome` for code style and linting.-- The project is configured with Biome's recommended rules.-- Run `bun x biome ci .` before committing to ensure your code follows the style guide.+We use **Biome** for formatting and linting. Before you commit:++```bash+pnpm run lint+pnpm run format+```++Most editors can auto-format on save if you install the Biome extension.-### Conventional Commits+### Commit Messages-- Use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages.-- Common types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`+We use [conventional commits](https://www.conventionalcommits.org/) to keep our history clean:++- `feat:` - New features+- `fix:` - Bug fixes+- `docs:` - Documentation changes+- `refactor:` - Code changes that don't add features or fix bugs+- `test:` - Adding or updating tests+- `chore:` - Maintenance tasks### Project Structure-- `apps/api/`: The backend API server.-- `apps/web/`: The frontend web application.-- `packages/`: Shared packages and configurations.+```+kaneo/+├── apps/+│ ├── api/ # Backend API (Node.js/Hono)+│ └── web/ # Frontend app (React/Vite)+├── packages/ # Shared code and configs+└── charts/ # Kubernetes Helm charts+```++### Testing++Run the test suite before submitting:++```bash+pnpm run test+```++If you're adding new features, please include tests.## Need Help?-- Check the [Discord server](https://discord.gg/rU4tSyhXXU) for help.-- Open an [issue](https://github.com/usekaneo/kaneo/issues) if you need help.+- **Discord**: Join our [Discord server](https://discord.gg/rU4tSyhXXU) for real-time help+- **Issues**: Open a [GitHub issue](https://github.com/usekaneo/kaneo/issues) for bugs or feature requests+- **Discussions**: Use GitHub Discussions for questions about contributing++## Types of Contributions We Love++- **Bug fixes** - Found something broken? Fix it!+- **New features** - Have an idea? Let's discuss it first+- **Documentation** - Help others understand how to use Kaneo+- **Performance improvements** - Make things faster+- **Accessibility** - Help make Kaneo usable for everyone+- **Testing** - More tests = more confidence-Thank you for your contribution to Kaneo! 🎉+Thanks for contributing to Kaneo! 🚀diff --git a/README.md b/README.mdindex 52720937c..e943b8759 100644--- a/README.md+++ b/README.md@@ -14,8 +14,6 @@</div>-<p align="center">An open source project management platform focused on simplicity and efficiency.</p>-<div align="center"><h3><a href="https://kaneo.app/quick-start">Quick Start</a>@@ -28,25 +26,28 @@</h3></div>-## ✨ Features+<p align="center">A modern, self-hosted project management platform that gets out of your way.</p>++## Why Kaneo?-- 🚀 **Simple & Fast**: Minimalist interface with powerful features-- 🔒 **Self-hosted**: Full control over your data-- 🎨 **Customizable**: Make it yours with extensive customization options-- 🤝 **Open Source**: MIT licensed, free forever+We built Kaneo because existing project management tools either feel bloated with features you'll never use, or they're too simple to handle real work. Kaneo finds the sweet spot—powerful enough for complex projects, simple enough that you'll actually want to use it.-## 🚀 Quick Start+**What makes it different:**+- **Clean interface** that focuses on your work, not the tool+- **Self-hosted** so your data stays yours+- **Actually fast** because we care about performance+- **Open source** and free forever-For a video walkthrough of getting started with Kaneo, check out our [Quick Start Guide on YouTube](https://www.youtube.com/watch?v=W2DwLtwH3k4).+## Getting Started-1. Create a `compose.yml` file with the following content:+The fastest way to try Kaneo is with Docker Compose. This sets up both the API and web interface:```yamlservices:backend:image: ghcr.io/usekaneo/api:latestenvironment:- JWT_ACCESS: "change_me"+ JWT_ACCESS: "your-secret-key-here"DB_PATH: "/app/apps/api/data/kaneo.db"ports:- 1337:1337@@ -66,82 +67,40 @@ volumes:sqlite_data:```-2. Run `docker compose up -d` to start the services.+Save this as `compose.yml`, run `docker compose up -d`, and open [http://localhost:5173](http://localhost:5173).-3. Open [http://localhost:5173](http://localhost:5173) in your browser.+> **Quick tip:** Change `JWT_ACCESS` to something secure in production. This is used to sign authentication tokens.-4. Create your first project and start managing your tasks!+### Configuration Options-| Variable | Description |-| -------- | ----------- |-| `KANEO_API_URL` | The URL of the API |-| `JWT_ACCESS` | Secret key for generating JWT tokens |-| `DB_PATH` | The path to the database file |-| `DISABLE_REGISTRATION` | Enable/disable new user registration (default: true) |+| Variable | What it does | Default |+| -------- | ------------ | ------- |+| `KANEO_API_URL` | Where the web app finds the API | Required |+| `JWT_ACCESS` | Secret key for user authentication | Required |+| `DB_PATH` | SQLite database location | `/app/apps/api/data/kaneo.db` |+| `DISABLE_REGISTRATION` | Block new user signups | `true` |-## 🚢 Kubernetes Deployment+## Kubernetes Deployment-Kaneo can also be deployed on Kubernetes using our Helm chart:--1. Clone this repository:+If you're running Kubernetes, we have a Helm chart that handles the complexity:```bash+# Clone the repogit clone https://github.com/usekaneo/kaneo.gitcd kaneo-```-2. Install the Helm chart:--```bash+# Install with Helmhelm install kaneo ./charts/kaneo --namespace kaneo --create-namespace-```-3. Access Kaneo:--```bash-# Port forward to access both services-kubectl port-forward svc/kaneo-web 5173:5173 -n kaneo &-kubectl port-forward svc/kaneo-api 1337:1337 -n kaneo &--# Access the application at http://localhost:5173-# The web frontend will communicate with the API at http://localhost:1337+# Access locally+kubectl port-forward svc/kaneo-web 5173:5173 -n kaneo```-### Production Deployments+Open [http://localhost:5173](http://localhost:5173) and you're good to go.-For production environments, we recommend using Ingress to expose Kaneo:+### Production Setup-```bash-# Basic installation with ingress-helm install kaneo ./charts/kaneo \- --namespace kaneo \- --create-namespace \- --set ingress.enabled=true \- --set ingress.className=nginx \- --set "ingress.hosts[0].host=kaneo.example.com"-```--For detailed production deployment examples, including:--- TLS configuration-- Cert-manager integration-- Path rewriting with regex capture groups-- Gateway API usage-- Resource configuration--Please refer to the [Helm chart documentation](./charts/kaneo/README.md).--### Local Deployments with Minikube--For local deployments with Minikube:--1. Start Minikube:--```bash-minikube start-```--2. Install the Helm chart with Ingress enabled:+For real deployments, you'll want proper ingress:```bashhelm install kaneo ./charts/kaneo \@@ -149,76 +108,58 @@ helm install kaneo ./charts/kaneo \--create-namespace \--set ingress.enabled=true \--set ingress.className=nginx \- --set "ingress.hosts[0].host=kaneo.local"-```--3. Enable the Ingress addon if not already enabled:--```bash-minikube addons enable ingress-```--4. Access Kaneo based on your OS:--#### macOS--For macOS, you need to use `minikube tunnel` to access the Ingress:--```bash-# Start minikube tunnel in a separate terminal-minikube tunnel+ --set "ingress.hosts[0].host=pm.yourcompany.com"```-Update your /etc/hosts file:+Check the [Helm chart docs](./charts/kaneo/README.md) for TLS setup, cert-manager integration, and other production considerations.-```bash-# Add to /etc/hosts-127.0.0.1 kaneo.local-```--Access Kaneo at http://kaneo.local+## Development-#### Linux/Windows--Get the Minikube IP:+Want to hack on Kaneo? Here's how to get a development environment running:```bash-minikube ip-```+# Clone and install dependencies+git clone https://github.com/usekaneo/kaneo.git+cd kaneo+pnpm install-Update your hosts file with the Minikube IP:+# Start the API+cd apps/api+pnpm run dev-```bash-# Add to /etc/hosts (Linux) or C:\Windows\System32\drivers\etc\hosts (Windows)-192.168.49.2 kaneo.local # Replace with the actual Minikube IP+# In another terminal, start the web app+cd apps/web+pnpm run dev```-Access Kaneo at http://kaneo.local+The API runs on port 1337, web app on 5173. Both will reload when you make changes.-## 📖 Documentation+## Community-For detailed instructions and documentation, visit our [Documentation](https://kaneo.app/quick-start).+- **[Discord](https://discord.gg/rU4tSyhXXU)** - Chat with users and contributors+- **[GitHub Issues](https://github.com/usekaneo/kaneo/issues)** - Bug reports and feature requests+- **[Documentation](https://kaneo.app/quick-start)** - Detailed guides and API docs-## 🤝 Contributing+## Contributing-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.+We're always looking for help, whether that's:+- Reporting bugs or suggesting features+- Improving documentation+- Contributing code+- Helping other users on Discord-## 💬 Community+Check out [CONTRIBUTING.md](CONTRIBUTING.md) for the details on how to get involved.-- [Discord](https://discord.gg/rU4tSyhXXU) - Chat with the community-- [GitHub Issues](https://github.com/usekaneo/kaneo/issues) - Report bugs or suggest features-- [Website](https://kaneo.app) - Official website+## License-## ❤️ Sponsors+MIT License - see [LICENSE](LICENSE) for details.-<!-- sponsors --><!-- sponsors -->+----## 👥 Contributors+<div align="center">+ <img src="https://repobeats.axiom.co/api/embed/3e8367ec2b2350e4fc48662df33c81dac657b833.svg" alt="Repobeats analytics image" />+</div><p align="center">- <img src="CONTRIBUTORS.svg" alt="Contributors" />+ Built with ❤️ by the Kaneo team and <a href="#contributors">contributors</a></p>--## 📝 License--This project is licensed under the [MIT License](LICENSE).