ci: add pr title check to enforce a consistent git history (#290)

.github/pull_request_template.md

@@ -3,11 +3,12 @@
 <!--
 Thank you for your Pull Request.
 
-Explain the context and why you're making that change. What is the problem
-you're trying to solve? If a new feature is being added, describe the intended
-use case that feature fulfills.
+Explain the context and why you're making that change.
+What is the problem you're trying to solve?
+If a new feature is being added,
+describe the intended use case that feature fulfills.
 
 Bug fixes and new features should include tests.
 
-Contributors guide: https://github.com/Valerioageno/tuono/blob/main/CONTRIBUTING.md
+PR guide: https://tuono.dev/documentation/contributing/pull-requests
 -->

.github/workflows/pr-title-checker.yml

@@ -0,0 +1,61 @@
+name: 'PR Title Checker'
+
+# This workflow ensures that PR titles adhere to a pattern
+# similar to conventional commits standard
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+      - labeled
+      - unlabeled
+
+env:
+  PR_TITLE: ${{ github.event.pull_request.title }}
+
+jobs:
+  check_pr_title:
+    name: 'PR Title Checker'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check type
+        id: type
+        # @warning Keep in sync with apps/documentation/src/routes/documentation/contributing/pull-requests.mdx
+        run: |
+          VALID_COMMIT_TYPES="chore|ci|docs|feat|fix|refactor|test"
+          REGEX="^${VALID_COMMIT_TYPES})(\(.*\))?!?: .*"
+
+          if ! [[ $PR_TITLE =~ $REGEX ]]; then
+            echo "::error title=Type::The title has an incorrect type. Valid types are ${VALID_COMMIT_TYPES}"
+            echo "result=fail" >> "$GITHUB_OUTPUT"
+          else
+            echo "::notice title=Type::The title is using a valid type"
+            echo "result=ok" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Check length
+        id: length
+        run: |
+          MAX_LENGTH=100
+          LENGTH=${#PR_TITLE}
+
+          if [ $LENGTH -gt $MAX_LENGTH ]; then
+            echo "::error title=Length::The title is longer than $MAX_LENGTH characters"
+            echo "result=fail" >> "$GITHUB_OUTPUT"
+          else
+            echo "::notice title=Length::The title length is within the maximum value of $MAX_LENGTH characters"
+            echo "result=ok" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Check result
+        env:
+          FAILURE: ${{ contains(join(steps.*.outputs.result, ','), 'fail') }}
+        run: |
+          echo "Failure: $FAILURE"
+          if [ "$FAILURE" = "false" ]; then
+            exit 0
+          else
+            exit 1
+          fi

CONTRIBUTING.md

@@ -23,6 +23,4 @@ Consider [opening a new issue](https://github.com/tuono-labs/tuono/issues/new/ch
 
 **Did you write a patch that fixes a bug?**
 
-- Open a new GitHub pull request with the patch.
-- Ensure the PR description clearly describes the problem and solution. Include the relevant issue number, if applicable.
-- The pull requests must pass all the CI pipelines
+[Visit the documentation to learn how to open a pull request](https://tuono.dev/documentation/contributing/pull-requests)

apps/documentation/src/components/navigation-buttons/navigation-buttons.tsx

@@ -1,16 +1,16 @@
 import type { JSX } from 'react'
 import { Box, Button, Text, Title, Flex } from '@mantine/core'
-import { Link } from 'tuono'
 import { IconArrowRight, IconArrowLeft } from '@tabler/icons-react'
+import { Link } from 'tuono'
 
-interface NavigationButton {
+interface NavigationButtonData {
   href: string
   title: string
 }
 
 interface NavigationButtonsProps {
-  prev?: NavigationButton
-  next?: NavigationButton
+  prev?: NavigationButtonData
+  next?: NavigationButtonData
 }
 
 export default function NavigationButtons({
@@ -25,7 +25,7 @@ export default function NavigationButtons({
   )
 }
 
-interface NavigationButtonProps extends NavigationButton {
+interface NavigationBtnProps extends NavigationButtonData {
   type: 'next' | 'prev'
 }
 
@@ -33,7 +33,7 @@ const NavigationBtn = ({
   type,
   title,
   href,
-}: NavigationButtonProps): JSX.Element => {
+}: NavigationBtnProps): JSX.Element => {
   const heading = type === 'next' ? 'Next' : 'Previous'
   const textAlign = type === 'next' ? 'left' : 'right'
   const variant = type === 'next' ? 'filled' : 'outline'

apps/documentation/src/components/sidebar/config.ts

@@ -260,6 +260,11 @@ export const sidebarElements: Array<SidebarElement> = [
         label: 'Local development',
         href: '/documentation/contributing/local-development',
       },
+      {
+        type: 'element',
+        label: 'Pull requests',
+        href: '/documentation/contributing/pull-requests',
+      },
     ],
   },
 ]

apps/documentation/src/routes/documentation/contributing/local-development.mdx

@@ -111,3 +111,16 @@ cargo build
 
 > On the documentation remember that `tuono` `npm` package is installed from the registry and
 > it is not linked to the repository.
+
+import NavigationButtons from '../../../components/navigation-buttons'
+
+<NavigationButtons
+  prev={{
+    title: 'Guidelines',
+    href: '/documentation/contributing',
+  }}
+  next={{
+    title: 'Pull requests',
+    href: '/documentation/contributing/pull-requests',
+  }}
+/>

apps/documentation/src/routes/documentation/contributing/pull-requests.mdx

@@ -0,0 +1,86 @@
+import MetaTags from '@/components/meta-tags'
+
+<MetaTags
+  title="Tuono - Opening a pull request"
+  canonical="https://tuono.dev/documentation/contributing/pull-requests"
+  description="Contribute to Tuono. Learn here how to open a pull request."
+/>
+
+import Breadcrumbs, { Element } from '@/components/breadcrumbs'
+
+<Breadcrumbs
+  breadcrumbs={[
+    { label: '✨ Contributing', href: '/documentation/contributing' },
+    { label: 'Pull Requests' },
+  ]}
+/>
+
+# Pull Requests
+
+Once your changes are ready, you can create a PR!
+
+If you are not familiar with GitHub pull requests,
+you can check the [official documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
+
+---
+
+- If you are fixing an issue, bear in mind to link the issue itself in the PR description.
+- If you are adding a new feature, describe the intended use case that the feature fulfills.
+
+> Bug fixes and new features should include tests.
+
+## Title
+
+The PR title must match the following format:
+
+```text
+<type>[optional scope]: <short description>
+```
+
+You can find commit examples in the [recent commits on main branch](https://github.com/tuono-labs/tuono/commits/main/)
+
+Here are some examples:
+
+- feat: add support for react 19
+- ci: create install-node-dependencies action
+- feat(packages/tuono-router): use React.Context to pass data
+- test(packages/tuono): messageChannel - use vi.fn
+
+> We do not care about the number, or style of commits in your branch history,
+> because we squash merge every PR into `main`.
+>
+> Feel free to commit in whatever style you feel comfortable with.
+
+### type
+
+Must be one of the following
+
+{/* @warning Keep in sync with .github/workflows/pr-title-checker.yml */}
+
+- `docs` - if you only change documentation, and not shipped code
+- `feat` - any new functionality additions
+- `fix` - any bug fixes that don't add new functionality
+- `refactor` - a code change that neither fixes a bug or adds a feature
+- `test` - if you only change tests, and not shipped code
+- `ci` - if you change something related to continuos integration
+- `chore` - anything else (e.g.: release)
+
+### optional scope
+
+A scope may be provided to a commit's type,
+to provide additional contextual information and is contained within parenthesis
+E.g.: `fix(crates/tuono): remove cargo warnings`
+
+### short description
+
+A succinct title for the PR.
+(The title max length is set to 100 characters)
+
+import NavigationButtons from '../../../components/navigation-buttons'
+
+<NavigationButtons
+  prev={{
+    title: 'Local development',
+    href: '/documentation/contributing/local-development',
+  }}
+/>