From 30324428b1db8cb9f3bfcf11f1c3f6fced9b60c2 Mon Sep 17 00:00:00 2001 From: Simon Reinisch Date: Tue, 29 Oct 2024 18:49:06 +0100 Subject: [PATCH] docs: improve contributing docs and simplify readme --- .github/CONTRIBUTING.md | 67 +++++++++++++++++++++++++------- .github/pull_request_template.md | 1 + README.md | 31 +++++---------- 3 files changed, 63 insertions(+), 36 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index a2fff28..3dd617a 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,26 +1,65 @@ -## Commit guidelines +# Table of contents -This project *strictly* follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). -Check out [their explanation](https://www.conventionalcommits.org/en/v1.0.0/#summary) of how to use it. -In this project we have the following scopes / types: +Welcome to ocularβ€”a small budgeting app as an alternative to Google sheet's annual budget planner. +Every contribution is welcome, no matter if it's a bug report, a feature request, or a pull request. +Make sure to check out the guidelines below before you start to make sure everything goes smoothly :) + +- [Table of contents](#table-of-contents) +- [Development](#development) + - [Setup](#setup) + - [Commit guidelines](#commit-guidelines) + - [Adding support for a new language](#adding-support-for-a-new-language) + - [Adding support for a new currency](#adding-support-for-a-new-currency) + - [Adding a new feature](#adding-a-new-feature) + +# Development + +## Setup + +Make sure you have the following installed: + +- [Node.js](https://nodejs.org/en/) (LTS version) +- [Docker](https://www.docker.com/) (for the backend) +- [pnpm](https://pnpm.io/) (for package management) + +After you've installed the required software, follow these steps: + +1. Clone this repository via `git clone https://github.com/simonwep/ocular`. +2. Run `pnpm install` in the root directory. +3. Copy the `.env.example` to `.env`, you can leave the default values. +4. Start the backend with `pnpm run genesis`. +5. Start the frontend with `pnpm run dev`. +6. Open `http://localhost:3000` in your browser. -### Scopes +You're now ready to start developing πŸš€ -* `core` - Core code, anything app / user-facing related. -* `setup` - Anything *only* relevant to the build-process / CI. +## Commit guidelines + +This project *strictly* follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). +Check out [their explanation](https://www.conventionalcommits.org/en/v1.0.0/#summary) in case you're not familiar with it. -### Types +Since this project's scope is rather small, we only use types to categorize our commits: * `feat` - A new feature. -* `refactor` - A refactoring. +* `chore` - A small task that doesn't add any new features or fix any bugs. +* `refactor` - A code change that neither fixes a bug nor adds a feature. * `fix` - A bug fix. -* `docs` - Documentation only. -* `improve` - Nothing changed, only improved (such as performance improvements). - +* `docs` - Documentation only changes. ## Adding support for a new language To add support for a new language, you need to do the following: -1. Add a new file under `src/i18n/locales` with the language code as the filename (e.g. `en.json`). -2. Import the file from step 1. in `src/i18n/index.ts` and add it to `messages`. +1. Add a new file under [`src/i18n/locales`](../src/i18n/locales) with the language code as the filename (e.g. `en.json`). +2. Import the file from step 1. in [`src/i18n/index.ts`](../src/i18n/index.ts) and add it to the `messages` constant. + +## Adding support for a new currency + +To add support for a new currency, you need to do the following: + +1. Add your currency code to [src/store/state/types.ts](../src/store/state/types.ts) to both `availableCurrencies` and `AvailableCurrency`. + +## Adding a new feature + +If you want to add a new feature, make sure to [create an issue](https://github.com/simonwep/ocular/issues/new/choose) first to discuss it, so we can make sure it fits the project's scope. +I appreciate every contribution, but I want to keep the project focused on its main goal. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 00497a5..f470680 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -9,4 +9,5 @@ - [ ] I have searched for a similar pull request. - [ ] The feature/bug-fix is tested carefully. - [ ] All irrelevant commits are squashed. (e.g. no `chore: fix eslint` commits). +- [ ] The branch is up to date with the base branch. diff --git a/README.md b/README.md index 999f7fa..ca3c5bd 100644 --- a/README.md +++ b/README.md @@ -23,15 +23,16 @@ - 🦾 Self-hosted. [Deploy](https://github.com/simonwep/ocular-docker) it via docker-compose in seconds. - πŸ•ΆοΈ Beautiful light and dark theme. -- πŸ’» Installable as a PWA. +- πŸ’» Installable as a PWA and ready for mobile. - πŸ”Ό Import your data from Google sheet's annual planner. - πŸ› οΈ Export your data as a single `.json`-file. - ✨ Dashboard with sankey diagram and a detailed view. - πŸŽ‡ Track budgets across multiple years. - πŸ™ˆ Privacy mode for when you're in a public place. -- ⚑️ Simple, fast and straight-forward UI. +- ⚑️ Simple, fast, and straight-forward UI. - πŸ«‚ User management and authentication. -- ...and more to come! +- 🌐 Multi-language and currency support. +- ...and much more! ## Summary @@ -41,28 +42,14 @@ Its goal is **not** to track individual expenses, work with multiple currencies This app comes with its own backend (by using [genesis](https://github.com/simonwep/genesis)), so the only thing you need to do is to host it somewhere. Your data stays on your server and is not shared with anyone else. -## Setup - -### Development - -1. Make sure you have the latest [node LTS](https://nodejs.org/en/) installed. -2. Install [pnpm](https://pnpm.io/) via `npm i -g pnpm`. -3. Clone this repository. -4. Run `pnpm install` in the root directory. -5. Copy the `.env.example` to `.env`, you can leave the default values. -6. Start the backend with `pnpm run genesis`. -7. Start the frontend with `pnpm run dev`. -8. Open `http://localhost:3000` in your browser. - -> [!NOTE] -> To modify the backend, head over to [genesis](https://github.com/simonwep/genesis). +## Getting started ### Production -This app can be deployed using [docker-compose](https://docs.docker.com/compose/). +Best deploy this app via [docker-compose](https://docs.docker.com/compose/). See [ocular-docker](https://github.com/simonwep/ocular-docker) for deployment. +Don't worry, it'll only take a few minutes to set everything up. -### Contributing +### Local development -If you want to work on this, make sure to out the [contributing guidelines](CONTRIBUTING.md) :) -Other than that, follow the steps under [development](#development) to get started. +If you want to work on this, make sure to out the [contributing guidelines](.github/CONTRIBUTING.md) :)