Pull Request guidelines

website/docs/guidelines/index.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 3
+---
+
+# Guidelines

website/docs/guidelines/pull-request/acceptance-criteria.md

@@ -0,0 +1,17 @@
+---
+sidebar_label: Contribution Acceptance Criteria
+sidebar_position: 3
+---
+
+# Contribution Acceptance Criteria
+
+To ensure that a PR can be approved, the following criteria must be met:
+
+- Code and comments must be written in English
+- A PR must contain the **smallest number of changes** possible allowing the feedback loop to be as quick as possible
+- If backward compatibility is broken, an explanation must be included. Make sure to include a migration guide within the changelog, using [changeset](changeset.md)
+- The changes must include passing unit tests. The only exception is for tests that expose an existing bug
+- The PR must be free of merge conflicts
+- The PR should address only **one specific issue** or add **only one feature**. Avoid combining multiple changes; always submit separate PRs for different issues or features
+- The CI pipeline must run successfully without errors
+- The PR should contain a changeset file to properly handle the versioning of the project

website/docs/guidelines/pull-request/changeset.md

@@ -0,0 +1,33 @@
+---
+sidebar_label: Changeset
+sidebar_position: 2
+---
+
+# Changeset
+
+This document provides guidelines on how to create and manage changesets, which are used to document and track changes in the codebase. Proper use of changesets ensures that all modifications are recorded systematically, facilitating easier tracking and auditing of changes over time.
+
+ ## Breaking Changes
+
+In cases where the code added in a PR breaks backward compatibility, a migration path or guide must be included in the changeset with `major` update. This ensures that users can transition smoothly to the new version without disruption.
+
+### Example
+
+```markdown
+---
+"dx-website": major
+---
+
+Upgrade to Turbo 2.x
+
+## Migration guide
+First, check the [official documentation](https://turbo.build/repo/docs/crafting-your-repository/upgrading) for any doubts.
+
+- Run `yarn dlx @turbo/codemod migrate` or `npx @turbo/codemod migrate` (official tool that should help to migrate. Follow the wizard)
+   - This will update the `turbo.json` file and try to install the latest version of `turbo`
+     - In case of errors, you can manually update the `turbo.json` file [following these steps](https://turbo.build/repo/docs/reference/turbo-codemod#turborepo-2x)
+     - In case it wasn't possible to install `turbo`, try to do it manually:
+       - `yarn add -D turbo`
+     - Now you should be ready to use the latest version of `turbo`
+ - Eventually, update the workflow pointing to a specific SHA
+```

website/docs/guidelines/pull-request/format.md

@@ -0,0 +1,60 @@
+---
+sidebar_label: Format
+sidebar_position: 1
+---
+
+# Format for Pull Requests
+
+This document outlines the required format for pull requests to ensure clarity and consistency.  
+Adhering to these guidelines will facilitate smoother reviews and better communication among team members.
+
+## Title
+
+The title of a pull request should be concise and meaningful, summarizing the changes made.  
+Keep the title within 72 characters to avoid truncation by GitHub.  
+Avoid including references to tracking systems (e.g., Jira task IDs) in the title, as they can clutter it and may not be useful for external reviewers.
+
+## Description
+
+The description of a pull request must explain the rationale behind the modifications, offering a brief overview of the updates along with any relevant context.  
+It should include:
+
+- A summary of the problem being solved or the feature being added
+- If applicable, include a reference to the tracking system at the end of the description using `Resolves #<Jira task ID>` (e.g., `Resolves #DX-1234`)
+
+### Tracking System References
+
+When referencing an activity, such as a Jira task, in a pull request, use one of [GitHub's supported keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) followed by the task ID.
+This ensures that the pull request is automatically linked to the relevant issue.
+We enforce the use of `Resolves #<issue-number>` in the description rather than the title. This approach allows for multiple issue references within the description while keeping the title clean and focused.  
+The reference should be placed on a separate line at the end of the description, preceded by a blank line for separation. The sentence should begin with an uppercase letter.
+
+### Examples
+
+#### Good Examples
+
+```markdown
+<Pull Request description>
+
+Resolves #DX-001
+```
+```markdown
+<Pull Request description>
+
+Close #DX-002 #CES-50
+```
+This applies when a single PR resolves multiple tasks tracked by different teams or boards.
+
+#### Bad Examples
+
+```markdown
+<Pull Request description>
+
+Close #DX-002 #DX-003
+```
+In this case, you should follow the [Contribution Acceptance Criteria](acceptance-criteria.md) and split the work into two separate PRs, each linked to a single task. This ensures better traceability and avoids merging unrelated changes together.
+
+```markdown
+This PR fixes #DX-002
+```
+This format is discouraged because the reference is embedded within the description, making it harder to read and potentially lacking a clear explanation of the issue being addressed. Instead, provide a meaningful description and place the reference on a separate line at the end.

website/docs/guidelines/pull-request/index.md

@@ -0,0 +1,5 @@
+# Pull Request
+
+Pull requests (PRs) are a critical part of the development workflow, enabling collaboration and code review.
+
+Establishing conventions for PRs ensures clarity and consistency, making it easier for team members to understand and review changes.