diff --git a/.husky/pre-push b/.husky/pre-push new file mode 100644 index 00000000..e6159dbb --- /dev/null +++ b/.husky/pre-push @@ -0,0 +1,33 @@ +#!/bin/sh + +# ─── Configuration ──────────────────────────────────────────────────────────── + +# Branches exempt from naming checks (space-separated) +PROTECTED_BRANCHES="development production" + +# Allowed prefixes for feature branches (space-separated) +ALLOWED_PREFIXES="feat content fix chore" + +# ────────────────────────────────────────────────────────────────────────────── + +branch=$(git symbolic-ref HEAD 2>/dev/null | sed 's|refs/heads/||') + +# Allow protected branches +for protected in $PROTECTED_BRANCHES; do + [ "$branch" = "$protected" ] && exit 0 +done + +# Build regex pattern from allowed prefixes +pattern=$(echo "$ALLOWED_PREFIXES" | sed 's/ /|/g') + +if ! echo "$branch" | grep -qE "^($pattern)/.+"; then + echo "ERROR: Branch name '$branch' does not follow the naming convention." + echo " Allowed prefixes: $(echo "$ALLOWED_PREFIXES" | sed 's/ /, /g')" + echo " Example: feat/, fix/" + echo "" + echo " To rename the current branch, run:" + echo " git branch -m " + exit 1 +fi + +exit 0 diff --git a/AGENTS.md b/AGENTS.md index d2f7d511..3fdcf783 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -134,7 +134,7 @@ All PRs to `development` and `production` run: - Default branch: `development` - Production branch: `production` (only merged from `development`) -- Branch naming: `feature/description` or `content/description` from +- Branch naming: `feat/description`, `content/description`, `fix/description`, or `chore/description` from `development` - PRs require review from `@Krzemien97` or `@bjsowa` (see `CODEOWNERS`) diff --git a/README.md b/README.md index 1ae77c96..466eec01 100644 --- a/README.md +++ b/README.md @@ -1,215 +1,215 @@ -# Fictionlab documentation - -Welcome to the Fictionlab documentation repository. This documentation is built -using [Docusaurus 3](https://docusaurus.io/), a modern static website generator. - -## Links - -- [Production link](http://docs.fictionlab.pl) -- [development (local) link](http://localhost:3000) - -## Getting Started - -### Prerequisites - -Ensure the following tools are installed on your local machine: - -- Code editor ([Visual Studio Code](https://code.visualstudio.com/) is - recommended) -- [Node.js](https://nodejs.org/en/) -- [Yarn 1.22.22 (Classic)](https://classic.yarnpkg.com/en/) -- [Git](https://git-scm.com/) -- A web browser - -#### Recommended VS Code extensions - - -> [!TIP] -> When opening this project in VS Code, you should be prompted to install the recommended extensions. If not, you can install them from the list below. - -- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) -- [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) -- [MDX](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) -- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - -### Cloning repository - -To clone the repository, execute the following command in your terminal: - -```sh -git clone https://github.com/fictionlab/docs -``` - -Alternatively, use the VS Code command palette: - -``` -> git clone -``` - -and paste the repository URL. - -By default, `development` branch is selected. To create new branch see -[Updating the Documentation](#updating-the-documentation). - -### Launching development environment - -After cloning the repository, open the folder in VS Code and run: - -``` -yarn install -``` - -To start the development environment, use: - -``` -yarn start -``` - -A new browser tab will open at http://localhost:3000, reflecting any changes -made to the files. - -### Updating docusaurus - -To update Docusaurus correctly, execute the following command: - -``` -yarn upgrade @docusaurus -L -``` - -Next, remove the `yarn.lock` file along with the `node_modules` and `build` directories. After deletion, regenerate the necessary files with updated dependency versions by running: - -``` -yarn install -``` - - -## Editing the documentation - -### Creating documents - -To create an entirely new page, create a new `.mdx` file in the desired folder -within the repository. Docusaurus maps the file structure relative to the -`/docs` folder into web URLs. - -For example: `/docs/leo-rover/specification.mdx` is translated to -`https://docs.fictionlab.pl/leo-rover/specification`. - - -> [!TIP] -> To avoid including the document name in the URL (e.g., creating a `leo-rover` page), name the document the same as the parent folder. -> Alternatively, you can name it `index.mdx`. For more information see: [Doc URLs - Docusaurus.io](https://docusaurus.io/docs/create-doc#doc-urls). - -### Editing documents - -To update the documentation, clone this repository and create a new branch from -`development` (or any other branch). For example, to create a branch named -`feature/new-button` from `development`: - -``` -git checkout -b feature/new-button development -``` - -Make necessary modifications and test everything using the development -environment. For guidelines on styling and formatting, refer to our -Documentation style guide - -[Documentation guidelines](https://docs.fictionlab.pl/guidelines). - - -> [!TIP] -> For more information on Docusaurus, visit [docusaurus.io](https://docusaurus.io/docs). - -### Testing implemented changes - -After making changes, test the compiled code in the browser. - - -> [!IMPORTANT] -> Always test your edits on both desktop and mobile browsers. -> -> Use developer tools to simulate mobile views (press F12 and select Toggle device emulation in Chrome-based browsers). - -Finally, check the spelling and formatting: - -``` -yarn formatcheck -``` - -This will list files requiring formatting changes, which you can fix manually. -To fix formatting automatically, use: - -``` -yarn format -``` - - -> [!CAUTION] -> Prettier has limited support for MDXv3. Automatic formatting can sometimes create unexpected results. -> -> For more details, see [docusaurus.io - usage with prettier](https://docusaurus.io/docs/markdown-features/admonitions#usage-with-prettier) - -If using -[Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) -extension, you can also use Prettier to only format current document. To do -this, in VS Code use **Shift+Alt+F** shortcut or type `> Format document` into -search bar. - -To check spelling, run: - -``` -yarn spellcheck -``` - -This will list unrecognized words in markdown files, which you must correct -manually. - - -> [!TIP] -> If you use the [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) -> extension in VS Code, documents will be spell-checked in real-time. Any unrecognized words will be displayed in the PROBLEMS tab of VS Code. - -Sometimes, CSpell will mistakenly mark correct words as unknown, including -custom names like ROS topics and variables. To remove this error, add the word -to the CSpell configuration. Right-click the word and select **Spelling** > -**Add words to the CSpell configuration**. This can be done either in the editor -or in the **PROBLEMS** tab of VS Code. - -In the editor, you can use the VS Code shortcut **Ctrl+.** to bring up the -**Quick Fix** menu, which provides the same options as mentioned above. - -### Pushing Changes to the Remote Repository - -When ready, push your changes using: - -``` -git push -``` - - -> [!TIP] -> For more information on using Git, see [Atlassian Git Tutorial](https://www.atlassian.com/git). - -After pushing changes, create a Pull Request to merge them into the -`development` branch. Your code will be reviewed by the Fictionlab team. Default -reviewers are: - -- [@Krzemien97](https://github.com/Krzemien97) -- [@bjsowa](https://github.com/bjsowa) - - -> [!WARNING] -> Pull requests to the `production` branch from any branch other than `development` will not be merged. - -### Branch Naming Conventions - -Follow these naming conventions for branches: - -- `/feature/description` - for new features, components etc. -- `/content/description` - for markdown content updates -- `/fix/description` - for fixes -- `/chore/description` - for dependency updates - -## Reporting Issues - -To report documentation issues, create an -[issue](https://github.com/fictionlab/docs/issues) on this repository or email -us at contact@fictionlab.pl. +# Fictionlab documentation + +Welcome to the Fictionlab documentation repository. This documentation is built +using [Docusaurus 3](https://docusaurus.io/), a modern static website generator. + +## Links + +- [Production link](http://docs.fictionlab.pl) +- [development (local) link](http://localhost:3000) + +## Getting Started + +### Prerequisites + +Ensure the following tools are installed on your local machine: + +- Code editor ([Visual Studio Code](https://code.visualstudio.com/) is + recommended) +- [Node.js](https://nodejs.org/en/) +- [Yarn 1.22.22 (Classic)](https://classic.yarnpkg.com/en/) +- [Git](https://git-scm.com/) +- A web browser + +#### Recommended VS Code extensions + + +> [!TIP] +> When opening this project in VS Code, you should be prompted to install the recommended extensions. If not, you can install them from the list below. + +- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) +- [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) +- [MDX](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) +- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) + +### Cloning repository + +To clone the repository, execute the following command in your terminal: + +```sh +git clone https://github.com/fictionlab/docs +``` + +Alternatively, use the VS Code command palette: + +``` +> git clone +``` + +and paste the repository URL. + +By default, `development` branch is selected. To create new branch see +[Updating the Documentation](#updating-the-documentation). + +### Launching development environment + +After cloning the repository, open the folder in VS Code and run: + +``` +yarn install +``` + +To start the development environment, use: + +``` +yarn start +``` + +A new browser tab will open at http://localhost:3000, reflecting any changes +made to the files. + +### Updating docusaurus + +To update Docusaurus correctly, execute the following command: + +``` +yarn upgrade @docusaurus -L +``` + +Next, remove the `yarn.lock` file along with the `node_modules` and `build` directories. After deletion, regenerate the necessary files with updated dependency versions by running: + +``` +yarn install +``` + + +## Editing the documentation + +### Creating documents + +To create an entirely new page, create a new `.mdx` file in the desired folder +within the repository. Docusaurus maps the file structure relative to the +`/docs` folder into web URLs. + +For example: `/docs/leo-rover/specification.mdx` is translated to +`https://docs.fictionlab.pl/leo-rover/specification`. + + +> [!TIP] +> To avoid including the document name in the URL (e.g., creating a `leo-rover` page), name the document the same as the parent folder. +> Alternatively, you can name it `index.mdx`. For more information see: [Doc URLs - Docusaurus.io](https://docusaurus.io/docs/create-doc#doc-urls). + +### Editing documents + +To update the documentation, clone this repository and create a new branch from +`development` (or any other branch). For example, to create a branch named +`feature/new-button` from `development`: + +``` +git checkout -b feature/new-button development +``` + +Make necessary modifications and test everything using the development +environment. For guidelines on styling and formatting, refer to our +Documentation style guide - +[Documentation guidelines](https://docs.fictionlab.pl/guidelines). + + +> [!TIP] +> For more information on Docusaurus, visit [docusaurus.io](https://docusaurus.io/docs). + +### Testing implemented changes + +After making changes, test the compiled code in the browser. + + +> [!IMPORTANT] +> Always test your edits on both desktop and mobile browsers. +> +> Use developer tools to simulate mobile views (press F12 and select Toggle device emulation in Chrome-based browsers). + +Finally, check the spelling and formatting: + +``` +yarn formatcheck +``` + +This will list files requiring formatting changes, which you can fix manually. +To fix formatting automatically, use: + +``` +yarn format +``` + + +> [!CAUTION] +> Prettier has limited support for MDXv3. Automatic formatting can sometimes create unexpected results. +> +> For more details, see [docusaurus.io - usage with prettier](https://docusaurus.io/docs/markdown-features/admonitions#usage-with-prettier) + +If using +[Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) +extension, you can also use Prettier to only format current document. To do +this, in VS Code use **Shift+Alt+F** shortcut or type `> Format document` into +search bar. + +To check spelling, run: + +``` +yarn spellcheck +``` + +This will list unrecognized words in markdown files, which you must correct +manually. + + +> [!TIP] +> If you use the [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) +> extension in VS Code, documents will be spell-checked in real-time. Any unrecognized words will be displayed in the PROBLEMS tab of VS Code. + +Sometimes, CSpell will mistakenly mark correct words as unknown, including +custom names like ROS topics and variables. To remove this error, add the word +to the CSpell configuration. Right-click the word and select **Spelling** > +**Add words to the CSpell configuration**. This can be done either in the editor +or in the **PROBLEMS** tab of VS Code. + +In the editor, you can use the VS Code shortcut **Ctrl+.** to bring up the +**Quick Fix** menu, which provides the same options as mentioned above. + +### Pushing Changes to the Remote Repository + +When ready, push your changes using: + +``` +git push +``` + + +> [!TIP] +> For more information on using Git, see [Atlassian Git Tutorial](https://www.atlassian.com/git). + +After pushing changes, create a Pull Request to merge them into the +`development` branch. Your code will be reviewed by the Fictionlab team. Default +reviewers are: + +- [@Krzemien97](https://github.com/Krzemien97) +- [@bjsowa](https://github.com/bjsowa) + + +> [!WARNING] +> Pull requests to the `production` branch from any branch other than `development` will not be merged. + +### Branch Naming Conventions + +Follow these naming conventions for branches: + +- `feat/description` - for new features, components etc. +- `content/description` - for markdown content updates +- `fix/description` - for fixes +- `chore/description` - for dependency updates + +## Reporting Issues + +To report documentation issues, create an +[issue](https://github.com/fictionlab/docs/issues) on this repository or email +us at contact@fictionlab.pl. diff --git a/package.json b/package.json index 0af034a4..3b406290 100644 --- a/package.json +++ b/package.json @@ -3,6 +3,7 @@ "version": "0.0.0", "private": true, "scripts": { + "prepare": "husky", "docusaurus": "docusaurus", "start": "docusaurus start", "build": "docusaurus build", @@ -40,6 +41,7 @@ "cspell": "^9.2.1", "glob": "^11.0.3", "gray-matter": "^4.0.3", + "husky": "^9.1.7", "prettier": "^3.6.2", "typescript": "^5.9.3", "yargs": "^18.0.0" diff --git a/yarn.lock b/yarn.lock index d4254a07..04b51b35 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5726,6 +5726,11 @@ human-signals@^2.1.0: resolved "https://registry.yarnpkg.com/human-signals/-/human-signals-2.1.0.tgz#dc91fcba42e4d06e4abaed33b3e7a3c02f514ea0" integrity sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw== +husky@^9.1.7: + version "9.1.7" + resolved "https://registry.yarnpkg.com/husky/-/husky-9.1.7.tgz#d46a38035d101b46a70456a850ff4201344c0b2d" + integrity sha512-5gs5ytaNjBrh5Ow3zrvdUUY+0VxIuWVL4i9irt6friV+BqdCfmV11CQTWMiBYWHbXhco+J1kHfTOUkePhCDvMA== + hyperdyperid@^1.2.0: version "1.2.0" resolved "https://registry.yarnpkg.com/hyperdyperid/-/hyperdyperid-1.2.0.tgz#59668d323ada92228d2a869d3e474d5a33b69e6b"