From a17039eda9c72fe7f65c63f29d354b716f19769d Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Wed, 19 Feb 2025 11:56:14 +0100 Subject: [PATCH 01/34] Add PR conventions file --- website/docs/conventions/pull-request.md | 35 ++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 website/docs/conventions/pull-request.md diff --git a/website/docs/conventions/pull-request.md b/website/docs/conventions/pull-request.md new file mode 100644 index 000000000..cc608ba56 --- /dev/null +++ b/website/docs/conventions/pull-request.md @@ -0,0 +1,35 @@ +--- +sidebar_label: Pull Request Conventions +sidebar_position: 4 +--- + +# Conventions for Pull Requests + +## Context + +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. + +## Title + +The title of a pull request should be concise and meaningful, summarizing the changes made. +The title's length should not be longer than 72 characters, because GitHub truncates it. +It should not include any references to tracking systems such as Jira task IDs. + +## Description + +## 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 + +[//]: # (- If the pr_enrich workflow assigns the size/large label, a justification for the PR's size must be provided) +- If backward compatibility is broken, an explanation must be included +- 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 + +## Examples From 05990199a9ade2b594ab75908a5f42a31d9322e8 Mon Sep 17 00:00:00 2001 From: Marco Comi <9998393+kin0992@users.noreply.github.com> Date: Wed, 19 Feb 2025 13:02:56 +0100 Subject: [PATCH 02/34] Update website/docs/conventions/pull-request.md Co-authored-by: Danilo Spinelli --- website/docs/conventions/pull-request.md | 1 + 1 file changed, 1 insertion(+) diff --git a/website/docs/conventions/pull-request.md b/website/docs/conventions/pull-request.md index cc608ba56..f5222962c 100644 --- a/website/docs/conventions/pull-request.md +++ b/website/docs/conventions/pull-request.md @@ -20,6 +20,7 @@ It should not include any references to tracking systems such as Jira task IDs. ## Description ## 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 From 7d1307a66d841c0f2c9802537eabd059d1488ffb Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Wed, 19 Feb 2025 13:07:17 +0100 Subject: [PATCH 03/34] Add reason why title should not contain Jira task id --- website/docs/conventions/pull-request.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/docs/conventions/pull-request.md b/website/docs/conventions/pull-request.md index f5222962c..bb6d51216 100644 --- a/website/docs/conventions/pull-request.md +++ b/website/docs/conventions/pull-request.md @@ -15,7 +15,8 @@ Establishing conventions for PRs ensures clarity and consistency, making it easi The title of a pull request should be concise and meaningful, summarizing the changes made. The title's length should not be longer than 72 characters, because GitHub truncates it. -It should not include any references to tracking systems such as Jira task IDs. + +It should not include any references to tracking systems such as Jira task IDs, as these can clutter the title and are not meaningful to external contributors or reviewers who do not have access to the tracking system. ## Description From aec329a6f01134feedec5397759a10247b86535b Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Wed, 19 Feb 2025 13:10:19 +0100 Subject: [PATCH 04/34] Improve breaking change description --- website/docs/conventions/pull-request.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/conventions/pull-request.md b/website/docs/conventions/pull-request.md index bb6d51216..28260cc0c 100644 --- a/website/docs/conventions/pull-request.md +++ b/website/docs/conventions/pull-request.md @@ -28,7 +28,7 @@ To ensure that a PR can be approved, the following criteria must be met: - A PR must contain the **smallest number of changes** possible [//]: # (- If the pr_enrich workflow assigns the size/large label, a justification for the PR's size must be provided) -- If backward compatibility is broken, an explanation must be included +- If backward compatibility is broken, an explanation must be included and a migration path as well - 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 From 6ce3ec59f6f998e595496a4594c359a0f8293c53 Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Wed, 19 Feb 2025 18:11:18 +0100 Subject: [PATCH 05/34] Create guidelines section --- website/docs/conventions/pull-request.md | 37 ----------------- .../code-review/conventional-comments.md | 4 ++ website/docs/guidelines/code-review/index.md | 1 + .../docs/guidelines/code-review/principles.md | 41 +++++++++++++++++++ website/docs/guidelines/git/branch-name.md | 4 ++ website/docs/guidelines/git/commit-message.md | 4 ++ website/docs/guidelines/git/index.md | 1 + website/docs/guidelines/index.md | 5 +++ .../pull-request/acceptance-criteria.md | 18 ++++++++ .../docs/guidelines/pull-request/changeset.md | 4 ++ .../docs/guidelines/pull-request/format.md | 20 +++++++++ website/docs/guidelines/pull-request/index.md | 5 +++ 12 files changed, 107 insertions(+), 37 deletions(-) delete mode 100644 website/docs/conventions/pull-request.md create mode 100644 website/docs/guidelines/code-review/conventional-comments.md create mode 100644 website/docs/guidelines/code-review/index.md create mode 100644 website/docs/guidelines/code-review/principles.md create mode 100644 website/docs/guidelines/git/branch-name.md create mode 100644 website/docs/guidelines/git/commit-message.md create mode 100644 website/docs/guidelines/git/index.md create mode 100644 website/docs/guidelines/index.md create mode 100644 website/docs/guidelines/pull-request/acceptance-criteria.md create mode 100644 website/docs/guidelines/pull-request/changeset.md create mode 100644 website/docs/guidelines/pull-request/format.md create mode 100644 website/docs/guidelines/pull-request/index.md diff --git a/website/docs/conventions/pull-request.md b/website/docs/conventions/pull-request.md deleted file mode 100644 index 28260cc0c..000000000 --- a/website/docs/conventions/pull-request.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -sidebar_label: Pull Request Conventions -sidebar_position: 4 ---- - -# Conventions for Pull Requests - -## Context - -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. - -## Title - -The title of a pull request should be concise and meaningful, summarizing the changes made. -The title's length should not be longer than 72 characters, because GitHub truncates it. - -It should not include any references to tracking systems such as Jira task IDs, as these can clutter the title and are not meaningful to external contributors or reviewers who do not have access to the tracking system. - -## Description - -## 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 - -[//]: # (- If the pr_enrich workflow assigns the size/large label, a justification for the PR's size must be provided) -- If backward compatibility is broken, an explanation must be included and a migration path as well -- 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 - -## Examples diff --git a/website/docs/guidelines/code-review/conventional-comments.md b/website/docs/guidelines/code-review/conventional-comments.md new file mode 100644 index 000000000..3601ce506 --- /dev/null +++ b/website/docs/guidelines/code-review/conventional-comments.md @@ -0,0 +1,4 @@ +--- +sidebar_label: Conventional Comments +sidebar_position: 2 +--- diff --git a/website/docs/guidelines/code-review/index.md b/website/docs/guidelines/code-review/index.md new file mode 100644 index 000000000..af3bcd504 --- /dev/null +++ b/website/docs/guidelines/code-review/index.md @@ -0,0 +1 @@ +# Code Review diff --git a/website/docs/guidelines/code-review/principles.md b/website/docs/guidelines/code-review/principles.md new file mode 100644 index 000000000..ee2ca3e06 --- /dev/null +++ b/website/docs/guidelines/code-review/principles.md @@ -0,0 +1,41 @@ +--- +sidebar_label: Principles +sidebar_position: 1 +--- + +# Principles + +## Responsibilities of the Pull Request Author +The author of a Pull Request (PR) is responsible for finding the optimal solution and implementing it. The author is responsible for verifying its correct functionality after release. +Before requesting a review, the author must ensure that: + +- The issue has been fully resolved +- The solution is implemented in the most appropriate way +- All required criteria have been met +- No bugs, logical issues, uncovered edge cases, or known vulnerabilities have been left in the code +- The best way to maximize the chances of having a PR approved without excessive iterations is to perform a self-review following the [Contribution Acceptance Criteria](../pull-request/acceptance-criteria.md). + + +During the self-review, the author should add comments within the PR to explain decisions, trade-offs, or areas where additional context would help the reviewer understand the code. + +## Before Requesting a Review +The author is expected to add comments to notify the reviewers of any important details or areas that require additional explanation or attention, such as: + +- The addition of a new library +- Potentially insecure code +- Non-obvious assumptions +### What NOT to Do +Do not add `TODO` comments in the source code unless specifically requested by the reviewer. If a `TODO` comment is added due to a pending task, it should include a reference, like: + +``` +# TODO: To be removed by https://pagopa.atlassian.net/browse/DX-0000 +``` +Do not add comments that simply explain what the code does. If a non-TODO comment is added, it should explain why something was done, not what the code does. + +Do not request a review for a PR if one or more CI checks are failing. +If the CI fails but a review is still necessary, make sure to leave a comment explaining the reasons. + +## Responsibilities of Reviewers +Reviewers are responsible for carefully examining the proposed solution and ensuring that the PR meets all [Contribution Acceptance Criteria](../pull-request/acceptance-criteria.md). + +They must also ensure that technical debt is kept under control, carefully evaluating when it makes sense to create follow-up tasks to address any documented debt introduced by the PR. diff --git a/website/docs/guidelines/git/branch-name.md b/website/docs/guidelines/git/branch-name.md new file mode 100644 index 000000000..cb9f27d52 --- /dev/null +++ b/website/docs/guidelines/git/branch-name.md @@ -0,0 +1,4 @@ +--- +sidebar_label: Branch Name +sidebar_position: 1 +--- diff --git a/website/docs/guidelines/git/commit-message.md b/website/docs/guidelines/git/commit-message.md new file mode 100644 index 000000000..4d47ce6a5 --- /dev/null +++ b/website/docs/guidelines/git/commit-message.md @@ -0,0 +1,4 @@ +--- +sidebar_label: Commit Message +sidebar_position: 2 +--- diff --git a/website/docs/guidelines/git/index.md b/website/docs/guidelines/git/index.md new file mode 100644 index 000000000..38eeffa4b --- /dev/null +++ b/website/docs/guidelines/git/index.md @@ -0,0 +1 @@ +# Git diff --git a/website/docs/guidelines/index.md b/website/docs/guidelines/index.md new file mode 100644 index 000000000..bab07e424 --- /dev/null +++ b/website/docs/guidelines/index.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 3 +--- + +# Guidelines diff --git a/website/docs/guidelines/pull-request/acceptance-criteria.md b/website/docs/guidelines/pull-request/acceptance-criteria.md new file mode 100644 index 000000000..dd0d8b8ef --- /dev/null +++ b/website/docs/guidelines/pull-request/acceptance-criteria.md @@ -0,0 +1,18 @@ +--- +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 + +[//]: # (- If the pr_enrich workflow assigns the size/large label, a justification for the PR's size must be provided) +- 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 diff --git a/website/docs/guidelines/pull-request/changeset.md b/website/docs/guidelines/pull-request/changeset.md new file mode 100644 index 000000000..f5101efa8 --- /dev/null +++ b/website/docs/guidelines/pull-request/changeset.md @@ -0,0 +1,4 @@ +--- +sidebar_label: Changeset +sidebar_position: 2 +--- diff --git a/website/docs/guidelines/pull-request/format.md b/website/docs/guidelines/pull-request/format.md new file mode 100644 index 000000000..709dfa47d --- /dev/null +++ b/website/docs/guidelines/pull-request/format.md @@ -0,0 +1,20 @@ +--- +sidebar_label: Pull Request Format +sidebar_position: 1 +--- + +# Format for Pull Requests + +## 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 should provide a detailed explanation of the changes made, the reasons for those changes, and 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: ` (e.g., `Resolves: DX-1234`) diff --git a/website/docs/guidelines/pull-request/index.md b/website/docs/guidelines/pull-request/index.md new file mode 100644 index 000000000..26723026e --- /dev/null +++ b/website/docs/guidelines/pull-request/index.md @@ -0,0 +1,5 @@ +# PR + +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. From 5d07c9812406d5e147a64eb2f054e016f8764a3e Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Wed, 19 Feb 2025 18:27:49 +0100 Subject: [PATCH 06/34] Start Git section --- website/docs/guidelines/git/branch-name.md | 36 ++++++++++++++++++++++ website/docs/guidelines/git/index.md | 3 ++ 2 files changed, 39 insertions(+) diff --git a/website/docs/guidelines/git/branch-name.md b/website/docs/guidelines/git/branch-name.md index cb9f27d52..3579e5167 100644 --- a/website/docs/guidelines/git/branch-name.md +++ b/website/docs/guidelines/git/branch-name.md @@ -2,3 +2,39 @@ sidebar_label: Branch Name sidebar_position: 1 --- + +# Branch Naming Conventions + +To maintain consistency and clarity in our Git workflow, branch names should follow the format `/`. The activity name should be **short, meaningful, and in plural form where applicable**, similar to how you would name a folder containing multiple related files. + +## Guidelines + +- **Keep branch names clean and focused.** Do not include tracking system activity IDs (e.g., Jira task IDs) in the branch name. Instead, [reference them in the PR description](../pull-request/format.md#description) +- **Use lowercase and hyphens (`-`)** to separate words for readability +- **Keep names concise but descriptive**, avoiding overly generic terms like `update` or `fix` + +## Activity Types + +Use one of the following types to categorize the branch activity: + +- `features/` – For new features +- `bugfixes/` – For bug fixes +- `hotfixes/` – For urgent production fixes +- `refactors/` – For code refactoring and reducing technical debt + +## Examples + +### Good Examples + +- `features/user-authentication` +- `bugfixes/login-errors` +- `hotfixes/payment-gateway` +- `refactors/dependency-updates` + +### Examples + +- `fix-bug` _(too vague)_ +- `new-feature` _(uncategorized)_ +- `update` _(lacks clarity)_ +- `v1.2.0-release` _(versioning should be handled via tags)_ +- `ui-redesign` _(should be `features/ui-redesign`)_ diff --git a/website/docs/guidelines/git/index.md b/website/docs/guidelines/git/index.md index 38eeffa4b..fbe922758 100644 --- a/website/docs/guidelines/git/index.md +++ b/website/docs/guidelines/git/index.md @@ -1 +1,4 @@ # Git + +- [Branch Naming Conventions](branch-name.md): guidelines for naming branches to maintain consistency and clarity in the Git workflow +- [Commit Message Format](commit-message.md): standards for writing commit messages that are clear, concise, and informative From 3136ee691738e89117746bdc965208fd095b240c Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Wed, 19 Feb 2025 19:35:56 +0100 Subject: [PATCH 07/34] Add short description --- website/docs/guidelines/pull-request/format.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/website/docs/guidelines/pull-request/format.md b/website/docs/guidelines/pull-request/format.md index 709dfa47d..e93fd7873 100644 --- a/website/docs/guidelines/pull-request/format.md +++ b/website/docs/guidelines/pull-request/format.md @@ -5,6 +5,9 @@ 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. From 1449636ba5276a38953c21165ed985cd65bee8e8 Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Wed, 19 Feb 2025 19:36:07 +0100 Subject: [PATCH 08/34] Improve sentence --- website/docs/guidelines/pull-request/acceptance-criteria.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guidelines/pull-request/acceptance-criteria.md b/website/docs/guidelines/pull-request/acceptance-criteria.md index dd0d8b8ef..993afe1cc 100644 --- a/website/docs/guidelines/pull-request/acceptance-criteria.md +++ b/website/docs/guidelines/pull-request/acceptance-criteria.md @@ -8,7 +8,7 @@ sidebar_position: 3 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 +- A PR must contain the **smallest number of changes** possible allowing the feedback loop to be as quick as possible [//]: # (- If the pr_enrich workflow assigns the size/large label, a justification for the PR's size must be provided) - If backward compatibility is broken, an explanation must be included. Make sure to include a migration guide within the changelog, using [changeset](changeset.md) From 36da4ad9018fe3f02dfeef049b520b7e7aea0243 Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Wed, 19 Feb 2025 19:49:10 +0100 Subject: [PATCH 09/34] Update changeset file --- .../pull-request/acceptance-criteria.md | 1 + .../docs/guidelines/pull-request/changeset.md | 29 +++++++++++++++++++ 2 files changed, 30 insertions(+) diff --git a/website/docs/guidelines/pull-request/acceptance-criteria.md b/website/docs/guidelines/pull-request/acceptance-criteria.md index 993afe1cc..02b274400 100644 --- a/website/docs/guidelines/pull-request/acceptance-criteria.md +++ b/website/docs/guidelines/pull-request/acceptance-criteria.md @@ -16,3 +16,4 @@ To ensure that a PR can be approved, the following criteria must be met: - 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 diff --git a/website/docs/guidelines/pull-request/changeset.md b/website/docs/guidelines/pull-request/changeset.md index f5101efa8..83a959e90 100644 --- a/website/docs/guidelines/pull-request/changeset.md +++ b/website/docs/guidelines/pull-request/changeset.md @@ -2,3 +2,32 @@ 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 +``` From 2ff812d04cc3bb590d3051bfa9450f0e9c7c5a92 Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Thu, 20 Feb 2025 11:11:25 +0100 Subject: [PATCH 10/34] Update PR format and front matter --- .../docs/guidelines/pull-request/format.md | 26 +++++++++++++++++-- website/docs/guidelines/pull-request/index.md | 2 +- 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/website/docs/guidelines/pull-request/format.md b/website/docs/guidelines/pull-request/format.md index e93fd7873..2ad18d035 100644 --- a/website/docs/guidelines/pull-request/format.md +++ b/website/docs/guidelines/pull-request/format.md @@ -1,5 +1,5 @@ --- -sidebar_label: Pull Request Format +sidebar_label: Format sidebar_position: 1 --- @@ -20,4 +20,26 @@ The description of a pull request should provide a detailed explanation of the c 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: ` (e.g., `Resolves: DX-1234`) +- If applicable, include a reference to the tracking system at the end of the description using `Resolves #` (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 #` 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. + +Here are some examples: + +- ```markdown + + + Resolves #DX-001 + ``` +- ```markdown + + + Close #DX-002 #DEV-003 + ``` + This is the case when the pull request is related to multiple issues on different boards. + diff --git a/website/docs/guidelines/pull-request/index.md b/website/docs/guidelines/pull-request/index.md index 26723026e..ab2fff0d4 100644 --- a/website/docs/guidelines/pull-request/index.md +++ b/website/docs/guidelines/pull-request/index.md @@ -1,4 +1,4 @@ -# PR +# Pull Request Pull requests (PRs) are a critical part of the development workflow, enabling collaboration and code review. From f04948777fa4cc4386f832d0f6f5b434b54a0e65 Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Thu, 20 Feb 2025 11:20:32 +0100 Subject: [PATCH 11/34] Add examples on PR description format --- .../docs/guidelines/pull-request/format.md | 35 +++++++++++++------ 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/website/docs/guidelines/pull-request/format.md b/website/docs/guidelines/pull-request/format.md index 2ad18d035..829bd8c16 100644 --- a/website/docs/guidelines/pull-request/format.md +++ b/website/docs/guidelines/pull-request/format.md @@ -29,17 +29,32 @@ This ensures that the pull request is automatically linked to the relevant issue We enforce the use of `Resolves #` 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. -Here are some examples: +#### Examples -- ```markdown - +##### Good Examples + +```markdown + + +Resolves #DX-001 +``` +```markdown + - Resolves #DX-001 - ``` -- ```markdown - +Close #DX-002 #CES-50 +``` +This applies when a single PR resolves multiple tasks tracked by different teams or boards. - Close #DX-002 #DEV-003 - ``` - This is the case when the pull request is related to multiple issues on different boards. +##### Bad Examples +```markdown + + +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. From f99112f8a7ce36e06f98945f348d71118392feff Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Thu, 20 Feb 2025 11:30:53 +0100 Subject: [PATCH 12/34] Remove files that have been moved in a separate PR --- .../code-review/conventional-comments.md | 4 -- website/docs/guidelines/code-review/index.md | 1 - .../docs/guidelines/code-review/principles.md | 41 ------------------- website/docs/guidelines/git/branch-name.md | 40 ------------------ website/docs/guidelines/git/commit-message.md | 4 -- website/docs/guidelines/git/index.md | 4 -- 6 files changed, 94 deletions(-) delete mode 100644 website/docs/guidelines/code-review/conventional-comments.md delete mode 100644 website/docs/guidelines/code-review/index.md delete mode 100644 website/docs/guidelines/code-review/principles.md delete mode 100644 website/docs/guidelines/git/branch-name.md delete mode 100644 website/docs/guidelines/git/commit-message.md delete mode 100644 website/docs/guidelines/git/index.md diff --git a/website/docs/guidelines/code-review/conventional-comments.md b/website/docs/guidelines/code-review/conventional-comments.md deleted file mode 100644 index 3601ce506..000000000 --- a/website/docs/guidelines/code-review/conventional-comments.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -sidebar_label: Conventional Comments -sidebar_position: 2 ---- diff --git a/website/docs/guidelines/code-review/index.md b/website/docs/guidelines/code-review/index.md deleted file mode 100644 index af3bcd504..000000000 --- a/website/docs/guidelines/code-review/index.md +++ /dev/null @@ -1 +0,0 @@ -# Code Review diff --git a/website/docs/guidelines/code-review/principles.md b/website/docs/guidelines/code-review/principles.md deleted file mode 100644 index ee2ca3e06..000000000 --- a/website/docs/guidelines/code-review/principles.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -sidebar_label: Principles -sidebar_position: 1 ---- - -# Principles - -## Responsibilities of the Pull Request Author -The author of a Pull Request (PR) is responsible for finding the optimal solution and implementing it. The author is responsible for verifying its correct functionality after release. -Before requesting a review, the author must ensure that: - -- The issue has been fully resolved -- The solution is implemented in the most appropriate way -- All required criteria have been met -- No bugs, logical issues, uncovered edge cases, or known vulnerabilities have been left in the code -- The best way to maximize the chances of having a PR approved without excessive iterations is to perform a self-review following the [Contribution Acceptance Criteria](../pull-request/acceptance-criteria.md). - - -During the self-review, the author should add comments within the PR to explain decisions, trade-offs, or areas where additional context would help the reviewer understand the code. - -## Before Requesting a Review -The author is expected to add comments to notify the reviewers of any important details or areas that require additional explanation or attention, such as: - -- The addition of a new library -- Potentially insecure code -- Non-obvious assumptions -### What NOT to Do -Do not add `TODO` comments in the source code unless specifically requested by the reviewer. If a `TODO` comment is added due to a pending task, it should include a reference, like: - -``` -# TODO: To be removed by https://pagopa.atlassian.net/browse/DX-0000 -``` -Do not add comments that simply explain what the code does. If a non-TODO comment is added, it should explain why something was done, not what the code does. - -Do not request a review for a PR if one or more CI checks are failing. -If the CI fails but a review is still necessary, make sure to leave a comment explaining the reasons. - -## Responsibilities of Reviewers -Reviewers are responsible for carefully examining the proposed solution and ensuring that the PR meets all [Contribution Acceptance Criteria](../pull-request/acceptance-criteria.md). - -They must also ensure that technical debt is kept under control, carefully evaluating when it makes sense to create follow-up tasks to address any documented debt introduced by the PR. diff --git a/website/docs/guidelines/git/branch-name.md b/website/docs/guidelines/git/branch-name.md deleted file mode 100644 index 3579e5167..000000000 --- a/website/docs/guidelines/git/branch-name.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -sidebar_label: Branch Name -sidebar_position: 1 ---- - -# Branch Naming Conventions - -To maintain consistency and clarity in our Git workflow, branch names should follow the format `/`. The activity name should be **short, meaningful, and in plural form where applicable**, similar to how you would name a folder containing multiple related files. - -## Guidelines - -- **Keep branch names clean and focused.** Do not include tracking system activity IDs (e.g., Jira task IDs) in the branch name. Instead, [reference them in the PR description](../pull-request/format.md#description) -- **Use lowercase and hyphens (`-`)** to separate words for readability -- **Keep names concise but descriptive**, avoiding overly generic terms like `update` or `fix` - -## Activity Types - -Use one of the following types to categorize the branch activity: - -- `features/` – For new features -- `bugfixes/` – For bug fixes -- `hotfixes/` – For urgent production fixes -- `refactors/` – For code refactoring and reducing technical debt - -## Examples - -### Good Examples - -- `features/user-authentication` -- `bugfixes/login-errors` -- `hotfixes/payment-gateway` -- `refactors/dependency-updates` - -### Examples - -- `fix-bug` _(too vague)_ -- `new-feature` _(uncategorized)_ -- `update` _(lacks clarity)_ -- `v1.2.0-release` _(versioning should be handled via tags)_ -- `ui-redesign` _(should be `features/ui-redesign`)_ diff --git a/website/docs/guidelines/git/commit-message.md b/website/docs/guidelines/git/commit-message.md deleted file mode 100644 index 4d47ce6a5..000000000 --- a/website/docs/guidelines/git/commit-message.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -sidebar_label: Commit Message -sidebar_position: 2 ---- diff --git a/website/docs/guidelines/git/index.md b/website/docs/guidelines/git/index.md deleted file mode 100644 index fbe922758..000000000 --- a/website/docs/guidelines/git/index.md +++ /dev/null @@ -1,4 +0,0 @@ -# Git - -- [Branch Naming Conventions](branch-name.md): guidelines for naming branches to maintain consistency and clarity in the Git workflow -- [Commit Message Format](commit-message.md): standards for writing commit messages that are clear, concise, and informative From e55fae21a849d6f966482ec5f11b584a7ab29bfd Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Thu, 20 Feb 2025 11:34:24 +0100 Subject: [PATCH 13/34] Update description --- website/docs/guidelines/pull-request/format.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/guidelines/pull-request/format.md b/website/docs/guidelines/pull-request/format.md index 829bd8c16..89f54d6d7 100644 --- a/website/docs/guidelines/pull-request/format.md +++ b/website/docs/guidelines/pull-request/format.md @@ -16,7 +16,7 @@ Avoid including references to tracking systems (e.g., Jira task IDs) in the titl ## Description -The description of a pull request should provide a detailed explanation of the changes made, the reasons for those changes, and any relevant context. +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 @@ -29,9 +29,9 @@ This ensures that the pull request is automatically linked to the relevant issue We enforce the use of `Resolves #` 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 +### Examples -##### Good Examples +#### Good Examples ```markdown @@ -45,7 +45,7 @@ Close #DX-002 #CES-50 ``` This applies when a single PR resolves multiple tasks tracked by different teams or boards. -##### Bad Examples +#### Bad Examples ```markdown From e5916d0a0a94b3e772b50c01f88a8a6c1e518bd6 Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Thu, 20 Feb 2025 11:36:57 +0100 Subject: [PATCH 14/34] Remove size criteria --- website/docs/guidelines/pull-request/acceptance-criteria.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/website/docs/guidelines/pull-request/acceptance-criteria.md b/website/docs/guidelines/pull-request/acceptance-criteria.md index 02b274400..5d600956e 100644 --- a/website/docs/guidelines/pull-request/acceptance-criteria.md +++ b/website/docs/guidelines/pull-request/acceptance-criteria.md @@ -9,8 +9,6 @@ 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 the pr_enrich workflow assigns the size/large label, a justification for the PR's size must be provided) - 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 From e4953daa4add74b85c51372cb59aee585be572c8 Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Thu, 20 Feb 2025 11:37:52 +0100 Subject: [PATCH 15/34] Update heading type --- website/docs/guidelines/pull-request/changeset.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guidelines/pull-request/changeset.md b/website/docs/guidelines/pull-request/changeset.md index 83a959e90..ce425436e 100644 --- a/website/docs/guidelines/pull-request/changeset.md +++ b/website/docs/guidelines/pull-request/changeset.md @@ -11,7 +11,7 @@ This document provides guidelines on how to create and manage changesets, which 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 +### Example ```markdown --- From f4566dc0262c45919bad1137af165199f5f7ac20 Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Thu, 20 Feb 2025 11:47:00 +0100 Subject: [PATCH 16/34] Fix formatting --- website/docs/guidelines/pull-request/format.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guidelines/pull-request/format.md b/website/docs/guidelines/pull-request/format.md index 89f54d6d7..63e4932f8 100644 --- a/website/docs/guidelines/pull-request/format.md +++ b/website/docs/guidelines/pull-request/format.md @@ -25,7 +25,7 @@ It should include: ### 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. +This ensures that the pull request is automatically linked to the relevant issue. We enforce the use of `Resolves #` 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. From 43166f6239b4f17c49bfc86b51c51acc7af14d52 Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Thu, 20 Feb 2025 11:48:38 +0100 Subject: [PATCH 17/34] Update title's description --- website/docs/guidelines/pull-request/format.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guidelines/pull-request/format.md b/website/docs/guidelines/pull-request/format.md index 63e4932f8..b3e31f6e2 100644 --- a/website/docs/guidelines/pull-request/format.md +++ b/website/docs/guidelines/pull-request/format.md @@ -11,7 +11,7 @@ Adhering to these guidelines will facilitate smoother reviews and better communi ## 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. +Keep the title within 72 characters to avoid truncation by GitHub, ensuring that the full title is visible in notifications and lists, which aids in quick identification and understanding of the PR's purpose. 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 From 9c343f2f098e0af5c90b7e00f05600e2f9617e41 Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Thu, 20 Feb 2025 12:09:00 +0100 Subject: [PATCH 18/34] Describe PR dependency and add more exaples --- .../docs/guidelines/pull-request/format.md | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/website/docs/guidelines/pull-request/format.md b/website/docs/guidelines/pull-request/format.md index b3e31f6e2..f2ba2827c 100644 --- a/website/docs/guidelines/pull-request/format.md +++ b/website/docs/guidelines/pull-request/format.md @@ -29,15 +29,34 @@ This ensures that the pull request is automatically linked to the relevant issue We enforce the use of `Resolves #` 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. +### Dependencies + +To express dependencies between different PRs, we use [dpulls, a GitHub dependency management tool](https://www.dpulls.com/). +This tool allows you to specify the dependencies between PRs, ensuring that they are merged in the correct order. +When creating a PR, you can specify the dependent PRs in the description using the `Depends on #` syntax. + +Add the dependency reference at the end of the description, preceding the tracking system reference, if present. + ### Examples #### Good Examples ```markdown - + +Depends on #42 Resolves #DX-001 ``` +`Depends on #42` indicates that this pull request relies on PR #42 and should not be merged until that dependency is resolved. +`Resolves #DX-001` specifies that this pull request addresses issue `DX-001`, ensuring proper issue tracking. + +```markdown + + +Depends on #42 +``` +This PR relies on PR #42 but does not resolve any specific issue. The dependency reference is still included to maintain clarity and ensure proper sequencing. + ```markdown From 7d529f2731cd4274a6d9c3f345d97f79b016a095 Mon Sep 17 00:00:00 2001 From: Marco Comi <9998393+kin0992@users.noreply.github.com> Date: Thu, 20 Feb 2025 12:10:17 +0100 Subject: [PATCH 19/34] Add changelog --- .changeset/grumpy-poets-do.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/grumpy-poets-do.md diff --git a/.changeset/grumpy-poets-do.md b/.changeset/grumpy-poets-do.md new file mode 100644 index 000000000..511f84fef --- /dev/null +++ b/.changeset/grumpy-poets-do.md @@ -0,0 +1,5 @@ +--- +"docs": minor +--- + +Create Pull Request guidelines From 45bb016e4f857f705351f3f8435473b361244f43 Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Thu, 20 Feb 2025 16:44:45 +0100 Subject: [PATCH 20/34] Add example for using changeset in a monorepo --- .../docs/guidelines/pull-request/changeset.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/website/docs/guidelines/pull-request/changeset.md b/website/docs/guidelines/pull-request/changeset.md index ce425436e..a3819f930 100644 --- a/website/docs/guidelines/pull-request/changeset.md +++ b/website/docs/guidelines/pull-request/changeset.md @@ -31,3 +31,28 @@ First, check the [official documentation](https://turbo.build/repo/docs/crafting - Now you should be ready to use the latest version of `turbo` - Eventually, update the workflow pointing to a specific SHA ``` + +## Monorepo + +When working with a monorepo, it is essential to manage changesets properly to ensure that all changes are documented and versioned correctly. +If you make changes on multiple workspaces, you should create a changeset for each workspace to maintain a clear and organized history of modifications. + +### Example + +```markdown +--- +"dx-website": patch +--- + +Fix typo in documentation +``` + +```markdown +--- +"package-A": minor +--- + +Update version of dependency `package-B` to `1.2.0` +``` + +Both changesets should be included in the same PR if they relate to the same feature or fix and require separate changelogs for the two packages. From 373c8b22fe7d8bcbee3beaf1cdd3cfeaf077cd9b Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Mon, 24 Feb 2025 09:56:08 +0100 Subject: [PATCH 21/34] Update description sencence --- website/docs/guidelines/pull-request/format.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guidelines/pull-request/format.md b/website/docs/guidelines/pull-request/format.md index f2ba2827c..0c02ac84b 100644 --- a/website/docs/guidelines/pull-request/format.md +++ b/website/docs/guidelines/pull-request/format.md @@ -26,7 +26,7 @@ It should include: 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 #` in the description rather than the title. This approach allows for multiple issue references within the description while keeping the title clean and focused. +We recommend placing issue references 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. ### Dependencies From 85067712cfb6dd26b251b846e6f9f6c33553cc8e Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Mon, 24 Feb 2025 09:58:44 +0100 Subject: [PATCH 22/34] Update acceptance criteria intro message --- website/docs/guidelines/pull-request/acceptance-criteria.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guidelines/pull-request/acceptance-criteria.md b/website/docs/guidelines/pull-request/acceptance-criteria.md index 5d600956e..c7df6efcc 100644 --- a/website/docs/guidelines/pull-request/acceptance-criteria.md +++ b/website/docs/guidelines/pull-request/acceptance-criteria.md @@ -5,7 +5,7 @@ sidebar_position: 3 # Contribution Acceptance Criteria -To ensure that a PR can be approved, the following criteria must be met: +To increase the likelihood of PR approval, consider meeting the following criteria: - 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 From d84775c94ca4ad857b360d52f7066d6590162669 Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Mon, 24 Feb 2025 10:40:25 +0100 Subject: [PATCH 23/34] Add principles in the index page --- website/docs/guidelines/pull-request/index.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/website/docs/guidelines/pull-request/index.md b/website/docs/guidelines/pull-request/index.md index ab2fff0d4..b1744fe0d 100644 --- a/website/docs/guidelines/pull-request/index.md +++ b/website/docs/guidelines/pull-request/index.md @@ -3,3 +3,13 @@ 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. + +## General Principles + +### Transparency + +Building transparency is crucial in the development process. [Opening pull requests in draft mode](https://github.blog/news-insights/product-news/introducing-draft-pull-requests/) is encouraged to solicit early feedback and foster open communication among team members. + +### Pragmatic Minimalism + +Adopting a pragmatic minimalism approach helps in maintaining focus on essential changes, avoiding unnecessary complexity, and ensuring that each pull request is concise and to the point. From a11ed25beba1031bd4b6ecf3f606c94f932128ba Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Tue, 25 Feb 2025 10:47:54 +0100 Subject: [PATCH 24/34] Update Transparency and Pragmatic Minimalism descriptions --- website/docs/guidelines/pull-request/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/guidelines/pull-request/index.md b/website/docs/guidelines/pull-request/index.md index b1744fe0d..5900e2914 100644 --- a/website/docs/guidelines/pull-request/index.md +++ b/website/docs/guidelines/pull-request/index.md @@ -8,8 +8,8 @@ Establishing conventions for PRs ensures clarity and consistency, making it easi ### Transparency -Building transparency is crucial in the development process. [Opening pull requests in draft mode](https://github.blog/news-insights/product-news/introducing-draft-pull-requests/) is encouraged to solicit early feedback and foster open communication among team members. +Transparency is crucial in the development process. [Opening pull requests in draft mode](https://github.blog/news-insights/product-news/introducing-draft-pull-requests/) is encouraged to provide visibility into ongoing work and foster collaboration. While draft PRs can facilitate early feedback, it is the author's responsibility to request it when needed. ### Pragmatic Minimalism -Adopting a pragmatic minimalism approach helps in maintaining focus on essential changes, avoiding unnecessary complexity, and ensuring that each pull request is concise and to the point. +Adopting a pragmatic minimalism approach means keeping pull requests small and focused on a single purpose. Avoid unnecessary complexity, and ensure clear PR descriptions and commit messages to help reviewers understand the intent quickly. From 8faa043c5b46749ce3f884a249fc403177c9c77c Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Tue, 25 Feb 2025 10:58:09 +0100 Subject: [PATCH 25/34] Clarify the use of GitHub key words --- website/docs/guidelines/pull-request/format.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/guidelines/pull-request/format.md b/website/docs/guidelines/pull-request/format.md index 0c02ac84b..bdc898f6e 100644 --- a/website/docs/guidelines/pull-request/format.md +++ b/website/docs/guidelines/pull-request/format.md @@ -24,8 +24,8 @@ It should include: ### 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. +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. +Although these keywords do not automatically link the pull request to Jira, we follow this convention to maintain consistency rather than introducing a new one. We recommend placing issue references 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. From 826d31e5e4c17bcf531d7f4d39c34475e209848e Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Tue, 25 Feb 2025 13:50:59 +0100 Subject: [PATCH 26/34] Create auto merge document --- website/docs/guidelines/pull-request/auto-merge.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 website/docs/guidelines/pull-request/auto-merge.md diff --git a/website/docs/guidelines/pull-request/auto-merge.md b/website/docs/guidelines/pull-request/auto-merge.md new file mode 100644 index 000000000..919f3f8ba --- /dev/null +++ b/website/docs/guidelines/pull-request/auto-merge.md @@ -0,0 +1,6 @@ +--- +sidebar_label: Auto Merge +sidebar_position: 2 +--- + +# Auto Merge From 93d2f7c084707f82936198c79e9e14fb42a788cb Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Tue, 25 Feb 2025 13:51:10 +0100 Subject: [PATCH 27/34] Update pages order --- website/docs/guidelines/pull-request/acceptance-criteria.md | 2 +- website/docs/guidelines/pull-request/changeset.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/guidelines/pull-request/acceptance-criteria.md b/website/docs/guidelines/pull-request/acceptance-criteria.md index c7df6efcc..299486933 100644 --- a/website/docs/guidelines/pull-request/acceptance-criteria.md +++ b/website/docs/guidelines/pull-request/acceptance-criteria.md @@ -1,6 +1,6 @@ --- sidebar_label: Contribution Acceptance Criteria -sidebar_position: 3 +sidebar_position: 4 --- # Contribution Acceptance Criteria diff --git a/website/docs/guidelines/pull-request/changeset.md b/website/docs/guidelines/pull-request/changeset.md index a3819f930..7e4693f23 100644 --- a/website/docs/guidelines/pull-request/changeset.md +++ b/website/docs/guidelines/pull-request/changeset.md @@ -1,6 +1,6 @@ --- sidebar_label: Changeset -sidebar_position: 2 +sidebar_position: 3 --- # Changeset From f4d717577dc38601804ddcd1ba4b8b99c5e8e570 Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Tue, 25 Feb 2025 13:58:13 +0100 Subject: [PATCH 28/34] Add introduction to auto merge --- website/docs/guidelines/pull-request/auto-merge.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/website/docs/guidelines/pull-request/auto-merge.md b/website/docs/guidelines/pull-request/auto-merge.md index 919f3f8ba..2209cbdd0 100644 --- a/website/docs/guidelines/pull-request/auto-merge.md +++ b/website/docs/guidelines/pull-request/auto-merge.md @@ -4,3 +4,10 @@ sidebar_position: 2 --- # Auto Merge + +[Auto-merge is a powerful feature in GitHub](https://github.blog/changelog/2021-02-04-pull-request-auto-merge-is-now-generally-available/) that allows pull requests to be merged automatically once they meet the required conditions, such as passing all status checks (CI pipeline, dependency with another PR, ...) or having approvals from the designated reviewers. +This feature simplifies the development process, reduces manual work, and ensures code is merged automatically when ready, saving time and avoiding delays. + +## Benefits of Auto-Merge + +## How to Enable Auto-Merge From bd8fd22ac625ed8632f9945c2c799a2f7f47108e Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Tue, 25 Feb 2025 14:03:39 +0100 Subject: [PATCH 29/34] Add benefits of auto merge feature --- website/docs/guidelines/pull-request/auto-merge.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/website/docs/guidelines/pull-request/auto-merge.md b/website/docs/guidelines/pull-request/auto-merge.md index 2209cbdd0..c8632d90d 100644 --- a/website/docs/guidelines/pull-request/auto-merge.md +++ b/website/docs/guidelines/pull-request/auto-merge.md @@ -8,6 +8,10 @@ sidebar_position: 2 [Auto-merge is a powerful feature in GitHub](https://github.blog/changelog/2021-02-04-pull-request-auto-merge-is-now-generally-available/) that allows pull requests to be merged automatically once they meet the required conditions, such as passing all status checks (CI pipeline, dependency with another PR, ...) or having approvals from the designated reviewers. This feature simplifies the development process, reduces manual work, and ensures code is merged automatically when ready, saving time and avoiding delays. -## Benefits of Auto-Merge +## Benefits of Auto Merge -## How to Enable Auto-Merge +- **Time Saving**: removes the need for manual intervention once the PR meets the conditions +- **Consistency**: it ensures that only code that passes all tests and reviews gets merged, maintaining high quality +- **Reduces the time to production**: by automating the merge process, code could be deployed faster + +## How to Enable Auto Merge From 6eb9afa8f0f8d7223fa507a3f667eb4f55047021 Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Tue, 25 Feb 2025 14:10:46 +0100 Subject: [PATCH 30/34] Add instruction to enable auto merge --- .../docs/guidelines/pull-request/auto-merge.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/website/docs/guidelines/pull-request/auto-merge.md b/website/docs/guidelines/pull-request/auto-merge.md index c8632d90d..d1bbeb6cf 100644 --- a/website/docs/guidelines/pull-request/auto-merge.md +++ b/website/docs/guidelines/pull-request/auto-merge.md @@ -5,13 +5,18 @@ sidebar_position: 2 # Auto Merge -[Auto-merge is a powerful feature in GitHub](https://github.blog/changelog/2021-02-04-pull-request-auto-merge-is-now-generally-available/) that allows pull requests to be merged automatically once they meet the required conditions, such as passing all status checks (CI pipeline, dependency with another PR, ...) or having approvals from the designated reviewers. -This feature simplifies the development process, reduces manual work, and ensures code is merged automatically when ready, saving time and avoiding delays. +[Auto-merge is a powerful feature in GitHub](https://github.blog/changelog/2021-02-04-pull-request-auto-merge-is-now-generally-available/) that automatically merges pull requests once they meet the required conditions, such as passing all status checks (e.g., CI pipeline, dependency on another PR) or receiving approvals from designated reviewers. +This feature simplifies the development process, reduces manual work, and ensures code is merged automatically when ready, saving time and avoiding delays. ## Benefits of Auto Merge -- **Time Saving**: removes the need for manual intervention once the PR meets the conditions -- **Consistency**: it ensures that only code that passes all tests and reviews gets merged, maintaining high quality -- **Reduces the time to production**: by automating the merge process, code could be deployed faster +- **Time Saving**: eliminates the need for manual intervention once the PR meets the conditions +- **Consistency**: ensures that only code passing all tests and reviews gets merged, maintaining high quality +- **Faster Time to Production**: automates the merge process, enabling faster deployment of code ## How to Enable Auto Merge + +You can enable auto-merge for a repository by following the [official GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request#enabling-auto-merge). + +If the repository settings are managed through [Terraform, using the `azure_github_environment_bootstrap` module](https://github.com/pagopa/dx/tree/main/infra/modules/azure_github_environment_bootstrap), auto-merge is enabled by default. +This means that while the feature is available for the repository, it does not automatically merge all PRs. From 8ca70fd5c011af0c93436808ab0a1de6f88eb6c7 Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Wed, 26 Feb 2025 12:08:29 +0100 Subject: [PATCH 31/34] Replace Terraform module link --- website/docs/guidelines/pull-request/auto-merge.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guidelines/pull-request/auto-merge.md b/website/docs/guidelines/pull-request/auto-merge.md index d1bbeb6cf..f17ee1520 100644 --- a/website/docs/guidelines/pull-request/auto-merge.md +++ b/website/docs/guidelines/pull-request/auto-merge.md @@ -18,5 +18,5 @@ This feature simplifies the development process, reduces manual work, and ensure You can enable auto-merge for a repository by following the [official GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request#enabling-auto-merge). -If the repository settings are managed through [Terraform, using the `azure_github_environment_bootstrap` module](https://github.com/pagopa/dx/tree/main/infra/modules/azure_github_environment_bootstrap), auto-merge is enabled by default. +If the repository settings are managed through [Terraform, using the `azure_github_environment_bootstrap` module](https://registry.terraform.io/modules/pagopa/dx-azure-github-environment-bootstrap/azurerm/latest), auto-merge is enabled by default. This means that while the feature is available for the repository, it does not automatically merge all PRs. From 39d17f0abcca924ab592a686467fda3b61d2f42b Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Wed, 5 Mar 2025 17:23:01 +0100 Subject: [PATCH 32/34] Update CI acceptance criteria --- website/docs/guidelines/pull-request/acceptance-criteria.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guidelines/pull-request/acceptance-criteria.md b/website/docs/guidelines/pull-request/acceptance-criteria.md index 299486933..74a77a687 100644 --- a/website/docs/guidelines/pull-request/acceptance-criteria.md +++ b/website/docs/guidelines/pull-request/acceptance-criteria.md @@ -13,5 +13,5 @@ To increase the likelihood of PR approval, consider meeting the following criter - 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 CI pipeline must run successfully without errors when the PR is _ready for review_. For Draft PRs, it is reasonable to have some errors as the PR is still in progress - The PR should contain a changeset file to properly handle the versioning of the project From 2079afc88d7b5a8d5414f7f9807b3f9540fc73bd Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Wed, 5 Mar 2025 17:23:55 +0100 Subject: [PATCH 33/34] Add new acceptance criteria --- website/docs/guidelines/pull-request/acceptance-criteria.md | 1 + 1 file changed, 1 insertion(+) diff --git a/website/docs/guidelines/pull-request/acceptance-criteria.md b/website/docs/guidelines/pull-request/acceptance-criteria.md index 74a77a687..d9d4a4c27 100644 --- a/website/docs/guidelines/pull-request/acceptance-criteria.md +++ b/website/docs/guidelines/pull-request/acceptance-criteria.md @@ -11,6 +11,7 @@ To increase the likelihood of PR approval, consider meeting the following criter - 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 +- No bugs, logical issues, uncovered edge cases, or known vulnerabilities have been left in the code - 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 when the PR is _ready for review_. For Draft PRs, it is reasonable to have some errors as the PR is still in progress From 4f9fcbe8a271cc02747a088b921e6752dba39bed Mon Sep 17 00:00:00 2001 From: Marco Comi Date: Thu, 6 Mar 2025 14:57:53 +0100 Subject: [PATCH 34/34] Format files --- .../pull-request/acceptance-criteria.md | 27 ++++-- .../guidelines/pull-request/auto-merge.md | 28 +++++-- .../docs/guidelines/pull-request/changeset.md | 45 ++++++---- .../docs/guidelines/pull-request/format.md | 83 +++++++++++++------ website/docs/guidelines/pull-request/index.md | 17 +++- 5 files changed, 141 insertions(+), 59 deletions(-) diff --git a/website/docs/guidelines/pull-request/acceptance-criteria.md b/website/docs/guidelines/pull-request/acceptance-criteria.md index d9d4a4c27..500cb1bb5 100644 --- a/website/docs/guidelines/pull-request/acceptance-criteria.md +++ b/website/docs/guidelines/pull-request/acceptance-criteria.md @@ -5,14 +5,25 @@ sidebar_position: 4 # Contribution Acceptance Criteria -To increase the likelihood of PR approval, consider meeting the following criteria: +To increase the likelihood of PR approval, consider meeting the following +criteria: - 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 -- No bugs, logical issues, uncovered edge cases, or known vulnerabilities have been left in the code +- 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 +- No bugs, logical issues, uncovered edge cases, or known vulnerabilities have + been left in the code - 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 when the PR is _ready for review_. For Draft PRs, it is reasonable to have some errors as the PR is still in progress -- The PR should contain a changeset file to properly handle the versioning of the project +- 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 when the PR is _ready for + review_. For Draft PRs, it is reasonable to have some errors as the PR is + still in progress +- The PR should contain a changeset file to properly handle the versioning of + the project diff --git a/website/docs/guidelines/pull-request/auto-merge.md b/website/docs/guidelines/pull-request/auto-merge.md index f17ee1520..0d5741d80 100644 --- a/website/docs/guidelines/pull-request/auto-merge.md +++ b/website/docs/guidelines/pull-request/auto-merge.md @@ -5,18 +5,30 @@ sidebar_position: 2 # Auto Merge -[Auto-merge is a powerful feature in GitHub](https://github.blog/changelog/2021-02-04-pull-request-auto-merge-is-now-generally-available/) that automatically merges pull requests once they meet the required conditions, such as passing all status checks (e.g., CI pipeline, dependency on another PR) or receiving approvals from designated reviewers. -This feature simplifies the development process, reduces manual work, and ensures code is merged automatically when ready, saving time and avoiding delays. +[Auto-merge is a powerful feature in GitHub](https://github.blog/changelog/2021-02-04-pull-request-auto-merge-is-now-generally-available/) +that automatically merges pull requests once they meet the required conditions, +such as passing all status checks (e.g., CI pipeline, dependency on another PR) +or receiving approvals from designated reviewers. +This feature simplifies the development process, reduces manual work, and +ensures code is merged automatically when ready, saving time and avoiding +delays. ## Benefits of Auto Merge -- **Time Saving**: eliminates the need for manual intervention once the PR meets the conditions -- **Consistency**: ensures that only code passing all tests and reviews gets merged, maintaining high quality -- **Faster Time to Production**: automates the merge process, enabling faster deployment of code +- **Time Saving**: eliminates the need for manual intervention once the PR meets + the conditions +- **Consistency**: ensures that only code passing all tests and reviews gets + merged, maintaining high quality +- **Faster Time to Production**: automates the merge process, enabling faster + deployment of code ## How to Enable Auto Merge -You can enable auto-merge for a repository by following the [official GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request#enabling-auto-merge). +You can enable auto-merge for a repository by following the +[official GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request#enabling-auto-merge). -If the repository settings are managed through [Terraform, using the `azure_github_environment_bootstrap` module](https://registry.terraform.io/modules/pagopa/dx-azure-github-environment-bootstrap/azurerm/latest), auto-merge is enabled by default. -This means that while the feature is available for the repository, it does not automatically merge all PRs. +If the repository settings are managed through +[Terraform, using the `azure_github_environment_bootstrap` module](https://registry.terraform.io/modules/pagopa/dx-azure-github-environment-bootstrap/azurerm/latest), +auto-merge is enabled by default. +This means that while the feature is available for the repository, it does not +automatically merge all PRs. diff --git a/website/docs/guidelines/pull-request/changeset.md b/website/docs/guidelines/pull-request/changeset.md index 7e4693f23..f38705b9a 100644 --- a/website/docs/guidelines/pull-request/changeset.md +++ b/website/docs/guidelines/pull-request/changeset.md @@ -5,11 +5,17 @@ sidebar_position: 3 # 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. +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 +## 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. +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 @@ -21,21 +27,29 @@ In cases where the code added in a PR breaks backward compatibility, a migration 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 + +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 ``` ## Monorepo -When working with a monorepo, it is essential to manage changesets properly to ensure that all changes are documented and versioned correctly. -If you make changes on multiple workspaces, you should create a changeset for each workspace to maintain a clear and organized history of modifications. +When working with a monorepo, it is essential to manage changesets properly to +ensure that all changes are documented and versioned correctly. +If you make changes on multiple workspaces, you should create a changeset for +each workspace to maintain a clear and organized history of modifications. ### Example @@ -55,4 +69,5 @@ Fix typo in documentation Update version of dependency `package-B` to `1.2.0` ``` -Both changesets should be included in the same PR if they relate to the same feature or fix and require separate changelogs for the two packages. +Both changesets should be included in the same PR if they relate to the same +feature or fix and require separate changelogs for the two packages. diff --git a/website/docs/guidelines/pull-request/format.md b/website/docs/guidelines/pull-request/format.md index bdc898f6e..e24283cb8 100644 --- a/website/docs/guidelines/pull-request/format.md +++ b/website/docs/guidelines/pull-request/format.md @@ -5,37 +5,58 @@ 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. +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, ensuring that the full title is visible in notifications and lists, which aids in quick identification and understanding of the PR's purpose. -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. +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, ensuring that +the full title is visible in notifications and lists, which aids in quick +identification and understanding of the PR's purpose. +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. +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 #` (e.g., `Resolves #DX-1234`) +- If applicable, include a reference to the tracking system at the end of the + description using `Resolves #` (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. -Although these keywords do not automatically link the pull request to Jira, we follow this convention to maintain consistency rather than introducing a new one. -We recommend placing issue references 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. +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. +Although these keywords do not automatically link the pull request to Jira, we +follow this convention to maintain consistency rather than introducing a new +one. +We recommend placing issue references 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. ### Dependencies -To express dependencies between different PRs, we use [dpulls, a GitHub dependency management tool](https://www.dpulls.com/). -This tool allows you to specify the dependencies between PRs, ensuring that they are merged in the correct order. -When creating a PR, you can specify the dependent PRs in the description using the `Depends on #` syntax. +To express dependencies between different PRs, we use +[dpulls, a GitHub dependency management tool](https://www.dpulls.com/). +This tool allows you to specify the dependencies between PRs, ensuring that they +are merged in the correct order. +When creating a PR, you can specify the dependent PRs in the description using +the `Depends on #` syntax. -Add the dependency reference at the end of the description, preceding the tracking system reference, if present. +Add the dependency reference at the end of the description, preceding the +tracking system reference, if present. ### Examples @@ -44,26 +65,32 @@ Add the dependency reference at the end of the description, preceding the tracki ```markdown -Depends on #42 -Resolves #DX-001 +Depends on #42 Resolves #DX-001 ``` -`Depends on #42` indicates that this pull request relies on PR #42 and should not be merged until that dependency is resolved. -`Resolves #DX-001` specifies that this pull request addresses issue `DX-001`, ensuring proper issue tracking. + +`Depends on #42` indicates that this pull request relies on PR #42 and should +not be merged until that dependency is resolved. +`Resolves #DX-001` specifies that this pull request addresses issue `DX-001`, +ensuring proper issue tracking. ```markdown Depends on #42 ``` -This PR relies on PR #42 but does not resolve any specific issue. The dependency reference is still included to maintain clarity and ensure proper sequencing. + +This PR relies on PR #42 but does not resolve any specific issue. The dependency +reference is still included to maintain clarity and ensure proper sequencing. ```markdown Close #DX-002 #CES-50 ``` -This applies when a single PR resolves multiple tasks tracked by different teams or boards. - + +This applies when a single PR resolves multiple tasks tracked by different teams +or boards. + #### Bad Examples ```markdown @@ -71,9 +98,17 @@ This applies when a single PR resolves multiple tasks tracked by different teams 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. + +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. + +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. diff --git a/website/docs/guidelines/pull-request/index.md b/website/docs/guidelines/pull-request/index.md index 5900e2914..0f1e012d6 100644 --- a/website/docs/guidelines/pull-request/index.md +++ b/website/docs/guidelines/pull-request/index.md @@ -1,15 +1,24 @@ # Pull Request -Pull requests (PRs) are a critical part of the development workflow, enabling collaboration and code review. +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. +Establishing conventions for PRs ensures clarity and consistency, making it +easier for team members to understand and review changes. ## General Principles ### Transparency -Transparency is crucial in the development process. [Opening pull requests in draft mode](https://github.blog/news-insights/product-news/introducing-draft-pull-requests/) is encouraged to provide visibility into ongoing work and foster collaboration. While draft PRs can facilitate early feedback, it is the author's responsibility to request it when needed. +Transparency is crucial in the development process. +[Opening pull requests in draft mode](https://github.blog/news-insights/product-news/introducing-draft-pull-requests/) +is encouraged to provide visibility into ongoing work and foster collaboration. +While draft PRs can facilitate early feedback, it is the author's responsibility +to request it when needed. ### Pragmatic Minimalism -Adopting a pragmatic minimalism approach means keeping pull requests small and focused on a single purpose. Avoid unnecessary complexity, and ensure clear PR descriptions and commit messages to help reviewers understand the intent quickly. +Adopting a pragmatic minimalism approach means keeping pull requests small and +focused on a single purpose. Avoid unnecessary complexity, and ensure clear PR +descriptions and commit messages to help reviewers understand the intent +quickly.