docs: move kk docs folder to src/content and move contributing guides to root
This commit is contained in:
parent
9f4b7c369a
commit
0f842a4323
|
@ -1,8 +1,3 @@
|
|||
---
|
||||
title: Development setup
|
||||
sidebarDepth: 3
|
||||
---
|
||||
|
||||
# Setup your development environment
|
||||
|
||||
## Introduction
|
||||
|
@ -34,7 +29,7 @@ to help you kickstart your contribution.
|
|||
|
||||
```ini
|
||||
CI_ENVIRONMENT="development"
|
||||
# If set to development, you must run `npm run dev` to start the static assets server
|
||||
# If set to development, you must run `pnpm run dev` to start the static assets server
|
||||
vite.environment="development"
|
||||
|
||||
# By default, this is set to true in the app config.
|
||||
|
@ -56,7 +51,7 @@ to help you kickstart your contribution.
|
|||
analytics.salt="DEV_ANALYTICS_SALT"
|
||||
|
||||
cache.handler="redis"
|
||||
cache.redis.host = "redis"
|
||||
cache.redis.host="redis"
|
||||
|
||||
# You may not want to use redis as your cache handler
|
||||
# Comment/remove the two lines above and uncomment
|
||||
|
@ -78,15 +73,16 @@ to help you kickstart your contribution.
|
|||
#media.s3.pathStyleEndpoint=true
|
||||
```
|
||||
|
||||
> _NB._ You can tweak your environment by setting more environment variables
|
||||
> in your custom `.env` file. See the `env` for examples or the
|
||||
> [!NOTE]
|
||||
> You can tweak your environment by setting more environment variables in
|
||||
> your custom `.env` file. See the `env` for examples or the
|
||||
> [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html)
|
||||
> for more info.
|
||||
|
||||
3. (for docker desktop) Add the repository you've cloned to docker desktop's
|
||||
`Settings` > `Resources` > `File Sharing`
|
||||
|
||||
### 2. (recommended) Develop inside the app Container with VSCode
|
||||
### 2. (recommended) Develop inside the app container with VSCode
|
||||
|
||||
If you're working in VSCode, you can take advantage of the `.devcontainer/`
|
||||
folder. It defines a development environment (dev container) with preinstalled
|
||||
|
@ -106,7 +102,7 @@ required services will be loaded automagically! 🪄
|
|||
|
||||
```bash
|
||||
# run Vite dev server
|
||||
npm run dev
|
||||
pnpm run dev
|
||||
```
|
||||
|
||||
If there is any issue with the php server not running, you can restart them
|
||||
|
@ -129,15 +125,15 @@ required services will be loaded automagically! 🪄
|
|||
# Composer is installed
|
||||
composer -V
|
||||
|
||||
# npm is installed
|
||||
npm -v
|
||||
# pnpm is installed
|
||||
pnpm -v
|
||||
|
||||
# git is installed
|
||||
git version
|
||||
```
|
||||
|
||||
For more info, see
|
||||
[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers)
|
||||
[Developing inside a Container](https://code.visualstudio.com/docs/devcontainers/containers)
|
||||
|
||||
### 3. Start hacking
|
||||
|
||||
|
@ -175,7 +171,7 @@ You do not wish to use the VSCode devcontainer? No problem!
|
|||
|
||||
```
|
||||
|
||||
> The `docker-compose up -d` command will boot 4 containers in the
|
||||
> The `docker-compose up -d` command will boot 5 containers in the
|
||||
> background:
|
||||
>
|
||||
> - `castopod_app`: a php based container with Castopod requirements
|
||||
|
@ -186,6 +182,7 @@ You do not wish to use the VSCode devcontainer? No problem!
|
|||
> persistent data
|
||||
> - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb
|
||||
> database.
|
||||
> - `castopod_s3`: a mock s3 server to work on the s3 fileManager
|
||||
|
||||
2. Run any command inside the containers by prefixing them with
|
||||
`docker-compose run --rm app`:
|
||||
|
@ -197,8 +194,8 @@ You do not wish to use the VSCode devcontainer? No problem!
|
|||
# use Composer
|
||||
docker-compose run --rm app composer -V
|
||||
|
||||
# use npm
|
||||
docker-compose run --rm app npm -v
|
||||
# use pnpm
|
||||
docker-compose run --rm app pnpm -v
|
||||
|
||||
# use git
|
||||
docker-compose run --rm app git version
|
||||
|
@ -216,57 +213,46 @@ You do not wish to use the VSCode devcontainer? No problem!
|
|||
composer install
|
||||
```
|
||||
|
||||
::: info Note
|
||||
> [!NOTE]
|
||||
> The php dependencies aren't included in the repository. Composer will check
|
||||
> the `composer.json` and `composer.lock` files to download the packages with
|
||||
> the right versions. The dependencies will live under the `vendor/` folder.
|
||||
> For more info, check out the
|
||||
> [Composer documentation](https://getcomposer.org/doc/).
|
||||
|
||||
The php dependencies aren't included in the repository. Composer will check
|
||||
the `composer.json` and `composer.lock` files to download the packages with
|
||||
the right versions. The dependencies will live under the `vendor/` folder.
|
||||
For more info, check out the
|
||||
[Composer documentation](https://getcomposer.org/doc/).
|
||||
|
||||
:::
|
||||
|
||||
2. Install javascript dependencies with [npm](https://www.npmjs.com/)
|
||||
2. Install javascript dependencies with [pnpm](https://pnpm.io/)
|
||||
|
||||
```bash
|
||||
npm install
|
||||
pnpm install
|
||||
```
|
||||
|
||||
::: info Note
|
||||
|
||||
The javascript dependencies aren't included in the repository. Npm will check
|
||||
the `package.json` and `package.lock` files to download the packages with the
|
||||
right versions. The dependencies will live under the `node_module` folder.
|
||||
For more info, check out the [NPM documentation](https://docs.npmjs.com/).
|
||||
|
||||
:::
|
||||
> [!NOTE]
|
||||
> The javascript dependencies aren't included in the repository. Pnpm will
|
||||
> check the `package.json` and `pnpm-lock.yaml` files to download the
|
||||
> packages with the right versions. The dependencies will live under the
|
||||
> `node_module` folder. For more info, check out the
|
||||
> [PNPM documentation](https://pnpm.io/motivation).
|
||||
|
||||
3. Generate static assets:
|
||||
|
||||
```bash
|
||||
# build all static assets at once
|
||||
npm run build:static
|
||||
pnpm run build:static
|
||||
|
||||
# build specific assets
|
||||
npm run build:icons
|
||||
npm run build:svg
|
||||
pnpm run build:icons
|
||||
pnpm run build:svg
|
||||
```
|
||||
|
||||
::: info Note
|
||||
|
||||
The static assets generated live under the `public/assets` folder, it
|
||||
includes javascript, styles, images, fonts, icons and svg files.
|
||||
|
||||
:::
|
||||
> [!NOTE]
|
||||
> The static assets generated live under the `public/assets` folder, it
|
||||
> includes javascript, styles, images, fonts, icons and svg files.
|
||||
|
||||
### Initialize and populate database
|
||||
|
||||
::: tip Tip
|
||||
|
||||
You may skip this section if you go through the install wizard (go to
|
||||
`/cp-install`).
|
||||
|
||||
:::
|
||||
> [!TIP]
|
||||
> You may skip this section if you go through the install wizard (go to
|
||||
> `/cp-install`).
|
||||
|
||||
1. Build the database with the migrate command:
|
||||
|
||||
|
@ -388,20 +374,17 @@ more insights.
|
|||
|
||||
### Allocation failed - JavaScript heap out of memory
|
||||
|
||||
This happens when running `npm install`.
|
||||
This happens when running `pnpm install`.
|
||||
|
||||
👉 By default, docker might not have access to enough RAM. Allocate more memory
|
||||
and run `npm install` again.
|
||||
and run `pnpm install` again.
|
||||
|
||||
### (Linux) Files created inside container are attributed to root locally
|
||||
|
||||
You may use Linux user namespaces to fix this on your machine:
|
||||
|
||||
::: info Note
|
||||
|
||||
Replace "username" with your local username
|
||||
|
||||
:::
|
||||
> [!NOTE]
|
||||
> Replace "username" with your local username
|
||||
|
||||
1. Go to `/etc/docker/daemon.json` and add:
|
||||
|
169
CONTRIBUTING.md
169
CONTRIBUTING.md
|
@ -1,4 +1,167 @@
|
|||
# Contributing guidelines
|
||||
# Contributing to Castopod
|
||||
|
||||
You may find the contributing guidelines in the
|
||||
[Castopod documentation website](https://docs.castopod.org/contributing/guidelines.html).
|
||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
||||
everybody!
|
||||
|
||||
> [!NOTE]
|
||||
> Castopod follows the [all contributors](https://allcontributors.org/)
|
||||
> specification in an effort to **recognize any kind of contribution**, not just
|
||||
> code!
|
||||
> If you've made a contribution and do not appear in the
|
||||
> [contributors](../index.md#contributors-✨) list, please
|
||||
> [let us know](../index.md#contact) so we can correct our mistake! 🙂
|
||||
|
||||
Please take a moment to review this document in order to make the contribution
|
||||
process easy and effective for everyone involved.
|
||||
|
||||
Following these guidelines helps to communicate that you respect the time of the
|
||||
developers managing and developing this open source project. In return, they
|
||||
should reciprocate that respect in addressing your issue or assessing patches
|
||||
and features.
|
||||
|
||||
## Translating Castopod
|
||||
|
||||
We use [Crowdin](https://translate.castopod.org/) to manage translation files
|
||||
for [Castopod](https://code.castopod.org/), the
|
||||
[documentation](https://docs.castopod.org/) and the
|
||||
[landing](https://castopod.org/) websites.
|
||||
|
||||
Whether you'd like to correct a translation error, validate new translations or
|
||||
include your language to Castopod, head into the
|
||||
[crowdin project](https://translate.castopod.org/) to get started.
|
||||
|
||||
> [!NOTE]
|
||||
> To prevent degrading user experience, new languages are included to Castopod
|
||||
> when they reach a certain threshold (~90%).
|
||||
|
||||
## Using the issue tracker
|
||||
|
||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
||||
preferred channel for [bug reports](#bug-reports),
|
||||
[features requests](#feature-requests) and
|
||||
[submitting pull requests](#pull-requests).
|
||||
|
||||
## ⚠️ Security issues and vulnerabilities
|
||||
|
||||
If you encounter any security issue or vulnerability in the Castopod source,
|
||||
please contact us directly by email at
|
||||
[security@castopod.org](mailto:security@castopod.org)
|
||||
|
||||
## Bug reports
|
||||
|
||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
||||
Good bug reports are extremely helpful - thank you!
|
||||
|
||||
Guidelines for bug reports:
|
||||
|
||||
1. **Use the issue search** — check if the issue has already been
|
||||
reported.
|
||||
|
||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
||||
latest `main` branch in the repository.
|
||||
|
||||
3. **Isolate the problem** — ideally create a
|
||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
||||
example.
|
||||
|
||||
A good bug report shouldn't leave others needing to chase you up for more
|
||||
information. Please try to be as detailed as possible in your report. What is
|
||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
||||
experience the problem? What would you expect to be the outcome? All these
|
||||
details will help people to fix any potential bugs.
|
||||
|
||||
> [!NOTE]
|
||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
||||
> have been created for this project. You may use them to help you follow those
|
||||
> guidelines.
|
||||
|
||||
## Feature requests
|
||||
|
||||
Feature requests are welcome. But take a moment to find out whether your idea
|
||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
||||
case to convince the project's developers of the merits of this feature. Please
|
||||
provide as much detail and context as possible.
|
||||
|
||||
## Pull requests
|
||||
|
||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
||||
They should remain focused in scope and avoid containing unrelated commits.
|
||||
|
||||
**Please ask first** before embarking on any significant pull request (e.g.
|
||||
implementing features, refactoring code, porting to a different language),
|
||||
otherwise you risk spending a lot of time working on something that the
|
||||
project's developers might not want to merge into the project.
|
||||
|
||||
Please adhere to the coding conventions used throughout a project (indentation,
|
||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
||||
|
||||
Adhering to the following process is the best way to get your work included in
|
||||
the project:
|
||||
|
||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
||||
project, clone your fork, and configure the remotes:
|
||||
|
||||
```bash
|
||||
# Clone your fork of the repo into the current directory
|
||||
git clone https://code.castopod.org/<your-username>/castopod.git
|
||||
|
||||
# Navigate to the newly cloned directory
|
||||
cd castopod
|
||||
|
||||
# Assign the original repo to a remote called "upstream"
|
||||
git remote add upstream https://code.castopod.org/adaures/castopod.git
|
||||
```
|
||||
|
||||
2. If you cloned a while ago, get the latest changes from upstream:
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull upstream main
|
||||
```
|
||||
|
||||
3. Create a new topic branch (off the `main` branch) to contain your feature,
|
||||
change, or fix:
|
||||
|
||||
```bash
|
||||
git checkout -b <topic-branch-name>
|
||||
```
|
||||
|
||||
4. Commit your changes in logical chunks. Please adhere to these
|
||||
[git commit message guidelines](https://conventionalcommits.org/) or your
|
||||
code is unlikely be merged into the main project. Use Git's
|
||||
[interactive rebase](https://help.github.com/articles/about-git-rebase/)
|
||||
feature to tidy up your commits before making them public.
|
||||
|
||||
5. Locally merge (or rebase) the upstream dev branch into your topic branch:
|
||||
|
||||
```bash
|
||||
git pull [--rebase] upstream main
|
||||
```
|
||||
|
||||
6. Push your topic branch up to your fork:
|
||||
|
||||
```bash
|
||||
git push origin <topic-branch-name>
|
||||
```
|
||||
|
||||
7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork)
|
||||
with a clear title and description.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> By submitting a patch, you agree to allow the project owners to license your
|
||||
> work under the terms of the
|
||||
> [GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/develop/LICENSE.md).
|
||||
|
||||
## Collaborating guidelines
|
||||
|
||||
There are few basic rules to ensure high quality of the project:
|
||||
|
||||
- Before merging, a PR requires at least two approvals from the collaborators
|
||||
unless it's an architectural change, a large feature, etc. If it is, then at
|
||||
least 50% of the core team have to agree to merge it, with every team member
|
||||
having a full veto right. (i.e. every single one can block any PR)
|
||||
- A PR should remain open for at least two days before merging (does not apply
|
||||
for trivial contributions like fixing a typo). This way everyone has enough
|
||||
time to look into it.
|
||||
|
||||
You are always welcome to discuss and propose improvements to this guideline.
|
||||
|
|
|
@ -31,12 +31,9 @@ please contact us directly by email at
|
|||
|
||||
Contributions are always welcome!
|
||||
|
||||
See the
|
||||
[contribution guidelines](https://docs.castopod.org/contributing/guidelines) for
|
||||
ways to get started.
|
||||
See the [contribution guidelines](./CONTRIBUTING.md) for ways to get started.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> [!Important]
|
||||
> **Any** contribution made on a repository other than
|
||||
> [the original repository](https://code.castopod.org/adaures/castopod) will not
|
||||
> be accepted.
|
||||
|
|
4451
docs/pnpm-lock.yaml
4451
docs/pnpm-lock.yaml
File diff suppressed because it is too large
Load Diff
|
@ -1,178 +0,0 @@
|
|||
---
|
||||
title: Guidelines
|
||||
---
|
||||
|
||||
# Contributing to Castopod
|
||||
|
||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
||||
everybody!
|
||||
|
||||
::: tip Note
|
||||
|
||||
Castopod follows the [all contributors](https://allcontributors.org/)
|
||||
specification in an effort to **recognize any kind of contribution**, not just
|
||||
code!
|
||||
|
||||
If you've made a contribution and do not appear in the
|
||||
[contributors](../index.md#contributors-✨) list, please
|
||||
[let us know](../index.md#contact) so we can correct our mistake! 🙂
|
||||
|
||||
:::
|
||||
|
||||
Please take a moment to review this document in order to make the contribution
|
||||
process easy and effective for everyone involved.
|
||||
|
||||
Following these guidelines helps to communicate that you respect the time of the
|
||||
developers managing and developing this open source project. In return, they
|
||||
should reciprocate that respect in addressing your issue or assessing patches
|
||||
and features.
|
||||
|
||||
## Translating Castopod
|
||||
|
||||
We use [Crowdin](https://translate.castopod.org/) to manage translation files
|
||||
for [Castopod](https://code.castopod.org/), the
|
||||
[documentation](https://docs.castopod.org/) and the
|
||||
[landing](https://castopod.org/) websites.
|
||||
|
||||
Whether you'd like to correct a translation error, validate new translations or
|
||||
include your language to Castopod, head into the
|
||||
[crowdin project](https://translate.castopod.org/) to get started.
|
||||
|
||||
::: info Note
|
||||
|
||||
To prevent degrading user experience, new languages are included to Castopod
|
||||
when they reach a certain threshold (~90%).
|
||||
|
||||
// TODO: ease acceptance criteria (to public pages?)
|
||||
|
||||
:::
|
||||
|
||||
## Using the issue tracker
|
||||
|
||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
||||
preferred channel for [bug reports](#bug-reports),
|
||||
[features requests](#feature-requests) and
|
||||
[submitting pull requests](#pull-requests).
|
||||
|
||||
## ⚠️ Security issues and vulnerabilities
|
||||
|
||||
If you encounter any security issue or vulnerability in the Castopod source,
|
||||
please contact us directly by email at
|
||||
[security@castopod.org](mailto:security@castopod.org)
|
||||
|
||||
## Bug reports
|
||||
|
||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
||||
Good bug reports are extremely helpful - thank you!
|
||||
|
||||
Guidelines for bug reports:
|
||||
|
||||
1. **Use the issue search** — check if the issue has already been
|
||||
reported.
|
||||
|
||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
||||
latest `main` branch in the repository.
|
||||
|
||||
3. **Isolate the problem** — ideally create a
|
||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
||||
example.
|
||||
|
||||
A good bug report shouldn't leave others needing to chase you up for more
|
||||
information. Please try to be as detailed as possible in your report. What is
|
||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
||||
experience the problem? What would you expect to be the outcome? All these
|
||||
details will help people to fix any potential bugs.
|
||||
|
||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
||||
> have been created for this project. You may use them to help you follow those
|
||||
> guidelines.
|
||||
|
||||
## Feature requests
|
||||
|
||||
Feature requests are welcome. But take a moment to find out whether your idea
|
||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
||||
case to convince the project's developers of the merits of this feature. Please
|
||||
provide as much detail and context as possible.
|
||||
|
||||
## Pull requests
|
||||
|
||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
||||
They should remain focused in scope and avoid containing unrelated commits.
|
||||
|
||||
**Please ask first** before embarking on any significant pull request (e.g.
|
||||
implementing features, refactoring code, porting to a different language),
|
||||
otherwise you risk spending a lot of time working on something that the
|
||||
project's developers might not want to merge into the project.
|
||||
|
||||
Please adhere to the coding conventions used throughout a project (indentation,
|
||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
||||
|
||||
Adhering to the following process is the best way to get your work included in
|
||||
the project:
|
||||
|
||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
||||
project, clone your fork, and configure the remotes:
|
||||
|
||||
```bash
|
||||
# Clone your fork of the repo into the current directory
|
||||
git clone https://code.castopod.org/<your-username>/castopod.git
|
||||
|
||||
# Navigate to the newly cloned directory
|
||||
cd castopod
|
||||
|
||||
# Assign the original repo to a remote called "upstream"
|
||||
git remote add upstream https://code.castopod.org/adaures/castopod.git
|
||||
```
|
||||
|
||||
2. If you cloned a while ago, get the latest changes from upstream:
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull upstream main
|
||||
```
|
||||
|
||||
3. Create a new topic branch (off the `main` branch) to contain your feature,
|
||||
change, or fix:
|
||||
|
||||
```bash
|
||||
git checkout -b <topic-branch-name>
|
||||
```
|
||||
|
||||
4. Commit your changes in logical chunks. Please adhere to these
|
||||
[git commit message guidelines](https://conventionalcommits.org/) or your
|
||||
code is unlikely be merged into the main project. Use Git's
|
||||
[interactive rebase](https://help.github.com/articles/about-git-rebase/)
|
||||
feature to tidy up your commits before making them public.
|
||||
|
||||
5. Locally merge (or rebase) the upstream dev branch into your topic branch:
|
||||
|
||||
```bash
|
||||
git pull [--rebase] upstream main
|
||||
```
|
||||
|
||||
6. Push your topic branch up to your fork:
|
||||
|
||||
```bash
|
||||
git push origin <topic-branch-name>
|
||||
```
|
||||
|
||||
7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork)
|
||||
with a clear title and description.
|
||||
|
||||
**IMPORTANT**: By submitting a patch, you agree to allow the project owners to
|
||||
license your work under the terms of the
|
||||
[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE).
|
||||
|
||||
## Collaborating guidelines
|
||||
|
||||
There are few basic rules to ensure high quality of the project:
|
||||
|
||||
- Before merging, a PR requires at least two approvals from the collaborators
|
||||
unless it's an architectural change, a large feature, etc. If it is, then at
|
||||
least 50% of the core team have to agree to merge it, with every team member
|
||||
having a full veto right. (i.e. every single one can block any PR)
|
||||
- A PR should remain open for at least two days before merging (does not apply
|
||||
for trivial contributions like fixing a typo). This way everyone has enough
|
||||
time to look into it.
|
||||
|
||||
You are always welcome to discuss and propose improvements to this guideline.
|
|
@ -157,9 +157,10 @@ so that you can understand what actions will and will not be tolerated.
|
|||
|
||||
### Contributing guide
|
||||
|
||||
Read our [contributing guide](./contributing/guidelines.md) to learn about our
|
||||
development process, how to propose bugfixes and improvements, and how to build
|
||||
and test your changes to Castopod.
|
||||
Read our
|
||||
[contributing guide](https://code.castopod.org/adaures/castopod/-/blob/develop/CONTRIBUTING.md)
|
||||
to learn about our development process, how to propose bugfixes and
|
||||
improvements, and how to build and test your changes to Castopod.
|
||||
|
||||
## Contributors ✨
|
||||
|
||||
|
|
Loading…
Reference in New Issue