From 8addf794b5cf1ebb59454dcd29a37388554450e6 Mon Sep 17 00:00:00 2001 From: JGBSouza Date: Sun, 5 Oct 2025 22:14:04 -0300 Subject: [PATCH 1/2] add: documentation: contribution: add issue tracking subsection As we are working on a free software environment, managing issues and contribution is a hard task, most of the times, there may have some pull requests closing some issue that haven't been revewed, and as it's not the most common approach search in a long list of pull requests if an issue is still on hold, there may be cases when other contributors may start to work on a problem that could be already solved. In this sense, this commit add a new section suggesting that the users should mention the issue related to the pull requests in the commentary, so github will automatically notify the issue that there is a pull request on hold for that, avoiding double work around it. Signed-off-by: JGBSouza --- CONTRIBUTING.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 71c85a7..ef069ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -184,6 +184,12 @@ When working on a pull request for patch-hub, you will often re-evaluate somethi Rewriting commits helps ensure the pull request shows only the final, intended changes. This improves reviewability and long-term maintainability by avoiding a noisy trail of intermediate fixes, making it easier for reviewers to understand the final result without tracking every small adjustment. It also benefits long-term maintainability by keeping the git history clean and meaningful, simplifying future debugging, version tracking, and change audits across the project’s lifecycle. +### Issues Tracking + +It’s recommended that each Pull Request reference the issue it addresses (e.g., Closes #123 or Resolves #123). If there isn’t an existing issue, consider creating one before opening the PR. + +Following this practice helps improve project organization and traceability, makes it easier for maintainers and contributors to assess proposed changes, and enables GitHub’s automatic linking between issues and PRs. This also clarifies that work is already underway, helping to prevent duplicated efforts—even before the PR is reviewed or merged. + ## Issue Reporting Use the preconfigured templates on GitHub to report issues and request features. If none of these fit your issue, you can use the "Blank" option. From 2770914815368aecdf91881de39e6cf055965678 Mon Sep 17 00:00:00 2001 From: JGBSouza Date: Sun, 5 Oct 2025 22:19:57 -0300 Subject: [PATCH 2/2] add: documentation: contribution: add more context on issue reporting Tracking implementations as issues in github may be very usefull for a free software context, as it can give more visibility of what is on development and let the others be able to discuss an implementation even before it starts, making it less likely that there will be an effort on developing a solution that will not be needed. In this sense add a few more context on issue tracking section, stating the need to always open a issue when there is no issue created for a future development. Signed-off-by: JGBSouza --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef069ce..c596286 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -192,6 +192,10 @@ Following this practice helps improve project organization and traceability, mak ## Issue Reporting +We suggest that all bugs, feature requests, and proposed changes be reported as issues. Contributors should create an issue describing the problem or proposal before starting work on a Pull Request. + +This approach ensures visibility, provides maintainers and contributors the opportunity to discuss the need and scope of the change, and helps others stay informed about ongoing work. + Use the preconfigured templates on GitHub to report issues and request features. If none of these fit your issue, you can use the "Blank" option. ## License