Issue management docs, auto-close and triage comment workflow (Lombiq…

… Technologies: OCORE-161) (#15820)

---------
Co-authored-by: Sébastien Ros <[email protected]>

.github/ISSUE_TEMPLATE/bug_report.md

@@ -6,6 +6,7 @@ labels: 'bug :bug:'
 assignees: ''
 
 ---
+<!-- Please also see the docs on how we manage issues: https://docs.orchardcore.net/en/latest/docs/guides/contributing/managing-issues/. -->
 
 ### Describe the bug
 

.github/ISSUE_TEMPLATE/config.yml

@@ -1,4 +1,4 @@
-blank_issues_enabled: true
+blank_issues_enabled: false
 contact_links:
   - name: Discussions
     url: https://github.com/OrchardCMS/OrchardCore/discussions/new

.github/ISSUE_TEMPLATE/feature_request.md

@@ -6,6 +6,7 @@ labels: enhancement
 assignees: ''
 
 ---
+<!-- Please also see the docs on how we manage issues: https://docs.orchardcore.net/en/latest/docs/guides/contributing/managing-issues/. -->
 
 ### Is your feature request related to a problem? Please describe.
 A clear and concise description of what the problem is.

.github/workflows/close_stale_prs.yml → .github/workflows/close_stale_prs_issues.yml

@@ -1,26 +1,34 @@
 # Labels PRs without updates for 60 days as stale, then closes them 15 days later.
-name: Close stale PRs
+# Labels issues that are labeled with "needs author feedback" without updates for 15 days as stale, then closes them 7 days later.
+name: Close Stale PRs and Issues
 
 on:
   schedule:
     # Every day at 1:39 AM UTC. A random time to avoid GitHub Actions being overloaded by scheduled workflows.
     - cron: '39 1 * * *'
 
 jobs:
-  close-stale-prs:
+  close-stale-prs-issues:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/stale@v9
         with:
           stale-pr-message: >
             It seems that this pull request didn't really move for quite a while. Is this something you'd like to 
-            revisit any time soon or should we close? Please comment if you'd like to pick it up and remove the 
-            "stale" label.
+            revisit any time soon or should we close? Please comment if you'd like to pick it up.
           stale-pr-label: stale
-          # Not marking issues as stale.
-          days-before-issue-stale: -1
           # Close the PR 15 days after marking it as stale.
-          days-before-close: 15
+          days-before-pr-close: 15
           close-pr-message: >
             Closing this pull request because it has been stale for very long. If you think this is still relevant, 
             feel free to reopen it.
+          stale-issue-message: >
+            It seems that this issue didn't really move for quite a while. Is this something you'd like to revisit 
+            any time soon or should we close? Please reply.
+          stale-issue-label: stale
+          days-before-issue-stale: 15
+          days-before-issue-close: 7
+          only-issue-labels: needs author feedback
+          close-issue-message: >
+            Closing this issue because it has been stale for very long. If you think this is still relevant, 
+            feel free to reopen it.

.github/workflows/comment_issue_on_triage.yml

@@ -0,0 +1,32 @@
+# Adds a comment on the issue when its milestone is set.
+name: Comment Issue on Triage
+
+on:
+  issues:
+    # Note that this is triggered also when the milestone changes. Preventing that would require jumping through a lot 
+    # of hoops, and that should be rare anyway.
+    types: [milestoned]
+
+jobs:
+  comment-issue-on-triage:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    if: github.event.issue.state == 'open'
+    steps:
+      - name: Add Comment
+        run: gh issue comment "$NUMBER" --body "$BODY"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          NUMBER: ${{ github.event.issue.number }}
+          # The double empty lines in the body are necessary; it'll show up as a single empty line in the comment.
+          BODY: >
+            We triaged this issue and set the milestone according to the priority we think is appropriate (see 
+            [the docs](https://docs.orchardcore.net/en/latest/docs/guides/contributing/managing-issues/) on how we 
+            triage and prioritize issues).
+
+
+            This indicates when the core team may start working on it. However, if you'd like to contribute, we'd 
+            warmly welcome you to do that anytime. See our guide on contributions 
+            [here](https://docs.orchardcore.net/en/latest/docs/guides/contributing/).

.github/workflows/first_time_contributor.yml

@@ -26,6 +26,8 @@ jobs:
           guide provides helpful information to ensure your contribution aligns with our standards. A core team member 
           will review your pull request.
         FIRST_PR_MERGED_COMMENT: >
-          Congratulations on your first PR merge! 🎉 Thank you for your contribution! We're looking forward to welcome 
+          Congratulations on your first PR merge! 🎉 Thank you for your contribution! We're looking forward to welcoming 
           other contributions of yours in the future. @all-contributors please add @{{ author }} for code.
-        STAR_MESSAGE: If you like Orchard Core, please star our repo and join our [community channels ](https://github.com/OrchardCMS/OrchardCore/?tab=readme-ov-file#get-in-touch)
+        STAR_MESSAGE: > 
+          If you like Orchard Core, please star our repo and join our 
+          [community channels](https://github.com/OrchardCMS/OrchardCore/?tab=readme-ov-file#get-in-touch).

mkdocs.yml

@@ -127,6 +127,7 @@ nav:
       - Query Content Items Based on Taxonomy: guides/query-content-items-based-on-taxonomy/README.md
       - Contributing:
           - Contributing to Orchard Core: guides/contributing/README.md
+          - Opening and managing issues: guides/contributing/managing-issues.md
           - Contributing code: guides/contributing/contributing-code.md
           - Contributing documentation: guides/contributing/contributing-documentation.md
           - Reviewing pull requests: guides/contributing/reviewing-pull-requests.md

src/docs/guides/contributing/README.md

@@ -6,6 +6,7 @@ First of all, thank you for thinking about contributing to Orchard Core!
 
 One of the easiest ways to contribute is to participate in discussions under [GitHub issues](https://github.com/OrchardCMS/OrchardCore/issues). You can also contribute by submitting pull requests with code changes, reviewing pull requests by others, assisting other community members on the [discussion board](https://github.com/OrchardCMS/OrchardCore/discussions), [evangelizing Orchard Core](https://github.com/Lombiq/Orchard-Ambassadors-Toolbox) in your own communities, or help organizing events.
 
+- [Opening and managing issues](managing-issues.md)
 - [Contributing code](contributing-code.md)
 - [Contributing documentation](contributing-documentation.md)
 - [Reviewing pull requests](reviewing-pull-requests.md)

src/docs/guides/contributing/contributing-code.md

@@ -26,9 +26,10 @@ First, clone the repository using the command `git clone https://github.com/Orch
 
 We warmly welcome fixes and features! Here are some resources to help you get started on how to contribute code:
 
-- Check out [the issue tracker](https://github.com/OrchardCMS/OrchardCore/issues) for open bug reports and feature requests. Prefer to select issues [scheduled for the upcoming release](https://github.com/OrchardCMS/OrchardCore/milestones). You can [sort issues by most commented](https://github.com/OrchardCMS/OrchardCore/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-desc) and [most thumbs up](https://github.com/OrchardCMS/OrchardCore/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc) (as well as other reactions similarly). These correlate with popularity, i.e. we can see what the community most wants. 
+- Check out [the issue tracker](https://github.com/OrchardCMS/OrchardCore/issues) for open bug reports and feature requests. Prefer to select issues [scheduled for the upcoming release](https://github.com/OrchardCMS/OrchardCore/milestones) (see the [issue management docs](managing-issues.md#issue-milestones) on what the milestones mean). You can [sort issues by most commented](https://github.com/OrchardCMS/OrchardCore/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-desc) and [most thumbs up](https://github.com/OrchardCMS/OrchardCore/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc) (as well as other reactions similarly). These correlate with popularity, i.e. we can see what the community most wants.
 - ["Good first issue" issues](https://github.com/OrchardCMS/OrchardCore/labels/good%20first%20issue): We think these are a good for newcomers.
 - ["Help wanted" issues](https://github.com/OrchardCMS/OrchardCore/labels/help%20wanted): These issues are up for grabs. Comment on an issue if you want to create a fix.
+- [Documentation issues](https://github.com/OrchardCMS/OrchardCore/labels/documentation) are quite suitable for newcomers too. See the [docs on contributing documentation](contributing-documentation.md).
 
 ## Identifying the scale
 

src/docs/guides/contributing/contributing-documentation.md

@@ -7,6 +7,9 @@ The [Orchard Core documentation site](https://docs.orchardcore.net/) is built wi
 !!! info
     Are you looking for information on contributing code? Head over to [here](contributing-code.md) instead.
 
+!!! tip
+    If you're looking for ideas on what to improve in the Orchard Core documentation, check out the [documentation issues](https://github.com/OrchardCMS/OrchardCore/labels/documentation).
+
 ## Editing documentation pages
 
 First, clone the repository using the command `git clone https://github.com/OrchardCMS/OrchardCore.git` and checkout the `main` branch. You can find the documentation files under the `src/docs` folder.

src/docs/guides/contributing/managing-issues.md

@@ -0,0 +1,42 @@
+# Opening and managing issues
+
+The [issue tracker on GitHub](https://github.com/OrchardCMS/OrchardCore/issues) is where we keep track of bug reports, feature requests, or items for other tasks. We ask you to choose a task from there when you [contribute](README.md), but opening an issue is a contribution too, so let's see some tips on that!
+
+## How to open an issue
+
+If you find a bug in Orchard Core, or have an idea for a new or improved feature, please open an issue [on GitHub](https://github.com/OrchardCMS/OrchardCore/issues/new/choose).
+
+- Please select the appropriate type, bug or feature request. This helps us assess your issue better!
+- Fill out the template, and please add as many details as possible. If you don't do this, then both you and another contributor will have to take time discussing what your issue is about.
+
+## What happens after you open an issue
+
+We triage issues every week on [the triage meeting](../../resources/meeting/README.md), as well as core contributors may comment on your issue before that. Please reply to any inquiries.
+
+Once your issue is triaged, one of the following things will happen:
+
+- A [milestone](https://github.com/OrchardCMS/OrchardCore/milestones) is assigned to it, see below. This means we think your issue is definitely worth addressing, thank you!
+- We close it. If your issue is a duplicate of an earlier one, is a report about a bug that's already fixed, or something that we don't think is a good match for Orchard Core, we'll close it with an explanation. This is not against you, it's just that we can't address all issues. Please don't hesitate to open new issues for other matters.
+
+## Issue milestones
+
+This is what [issue milestones](https://github.com/OrchardCMS/OrchardCore/milestones) mean:
+
+- The next patch version (`1.2.something`, e.g. if the current version is `1.2.3`, then `1.2.4`) indicates the highest priority for serious regressions and other urgent bug fixes that we intend to fix ASAP and publish in a patch release.
+- The next minor version (`1.something`, e.g. `1.3` if the current version if `1.2.0`) is for less urgent bug fixes and feature requests that we still think should be addressed in the next planned release. Regressions since the last release found by those from the community who live on the edge and use the [preview releases](../../getting-started/preview-package-source.md) are marked as such too.
+- Some later minor version (literally `1.x` if the current version is `1.anything`) is for issues that we intend to address eventually, maybe.
+- The `backlog` milestone is for everything else that we think is a valid request, but we won't work on it any time soon.
+
+## Managing issues as a core contributor
+
+Some tips on issue management:
+
+- An issue should be about a concrete task, some change in Orchard Core or how we run the project. If it's a question or discussion, then [convert it into a discussion](https://docs.github.com/en/discussions/managing-discussions-for-your-community/moderating-discussions#converting-an-issue-to-a-discussion).
+- Set the milestone according to the above logic, or close the issue with a comment elaborating the reason.
+- Add further labels for categorization (external contributors can't add labels). E.g.:
+    - Add "good first issue" if the issue looks suitable for a novice contributor.
+    - Add "perf" if it's about performance.
+    - Add module/feature set-related labels, like "Media" or "OpenId".
+    - Add "security" for security issues.
+- Change the issue's title if it contains errors or is unclear/incorrect.
+- If you asked the author something and the issue should be closed if they don't reply, add the `needs author feedback` label. This will automatically mark the issue as stale after 15 days, and then close it after another 7.

src/docs/guides/contributing/reviewing-pull-requests.md

@@ -16,9 +16,10 @@ If the PR is coming from a fork, working with its code locally won't be as trivi
 ## Tips on managing pull requests
 
 !!! note
-    Adding labels and merging pull requests is only available for core contributors. Otherwise, anybody can review pull requests.
+    Adding labels and otherwise updating a pull request, as well as merging them are only available for core contributors. Otherwise, anybody can review the changes in pull requests and comment on them.
 
-- [Here's a list](https://github.com/OrchardCMS/OrchardCore/pulls?q=is%3Apr+is%3Aopen+reviewed-by%3A%40me) of open PRs reviewed by you. Maybe check them because perhaps it's time to ping the authors since maybe they forgot to follow up. Or maybe you forgot to merge a PR? 
+- [Here's a list](https://github.com/OrchardCMS/OrchardCore/pulls?q=is%3Apr+is%3Aopen+reviewed-by%3A%40me) of open PRs reviewed by you. Maybe check them because perhaps it's time to ping the authors since maybe they forgot to follow up. Or maybe you forgot to merge a PR?
+- Change the PR's title if it contains errors or is unclear/incorrect.
 - Add the "don't merge" label on PRs that are ready for review, approved by you and/or others, but you asked more people for feedback before it can be merged.
 - Add the "needs triage" label on PRs that you think should be checked by others during the weekly triage meeting too. Explain in a comment why you deem this is necessary.
 - Be sure to merge PRs that don't need a second opinion. This is especially important for external contributors who can't merge their PRs. Keeping PRs open will make them collect merge conflicts and make the contributor demotivated.