|
| 1 | + |
| 2 | +We're now using GitHub for all our development activities; it is important for everyone to use a consistent process. Hence we have this guideline. |
| 3 | + |
| 4 | +> [!NOTE] |
| 5 | +> 1. Although this doc uses the term 'issue', this guideline applies to both GitHub issues and Pull Requests. |
| 6 | +> 2. We are an open-source project, GitHub issues and PRs are not your personal notebook, it is open to the public, and we use these tool to communicate and collaborate. |
| 7 | +
|
| 8 | +## GitHub Issue Management |
| 9 | + |
| 10 | +High-quality issues are at the core of helping a project to succeed. While some may see issues as merely a big list of problems you have to tend to, well-managed, triaged, and labeled issues can provide incredible insight into your code, your community, and where the problem spots are. |
| 11 | + |
| 12 | +### What is an issue |
| 13 | + |
| 14 | +* Issue queues should mirror your thought process. Issues are where you structure your ideas with others or alone. |
| 15 | +* Issues should focus on ideas, problems, and solutions; they are not activity trackers. While you want to share your ideas as they unfold, you may not want to comment on every little activity you register on an issue; for this, IM, commit messages, or a Scrum meeting may be better suited. |
| 16 | +* The issue queue is where real collaboration is done. Other forms of communication (verbal discussions, email, IM…) should happen after exploring an issue. This ensured that everyone involved had a chance to make and review the arguments cleanly, structured, and transparently. The more real-time the discussion, the more likely it is to be charged with emotions. |
| 17 | + |
| 18 | +### How to write issues (and PRs and everything else) |
| 19 | + |
| 20 | +**Avoid duplication** |
| 21 | + |
| 22 | +The first thing you should do when writing a GitHub issue is to use the search feature to make sure an issue doesn’t already exist. |
| 23 | + |
| 24 | +When duplicate issues are found, one of them should be closed — typically the less thorough one. Be sure the closing comment contains a link to the issue remaining open (e.g. “Duplicate of #123”), and that any helpful details from the closed issue are consolidated into the open one. |
| 25 | + |
| 26 | +**Titles are important** |
| 27 | + |
| 28 | +Keep your titles short and descriptive; please note that the title is your issue's most visible part. |
| 29 | + |
| 30 | +When someone reads your title, it should provide enough information about this issue without opening the issue details page. |
| 31 | + |
| 32 | +You should NEVER just drop two or three words as an issue title so that nobody understands what this issue is for. |
| 33 | + |
| 34 | +When requesting features and changes, clearly describe the problem to be solved instead of prescribing a solution. |
| 35 | + |
| 36 | + * Bad — "Make the button red." |
| 37 | + * Good — "The user doesn’t understand that deletion is irreversible." |
| 38 | + |
| 39 | +Sometimes we add prefixes to the issue. In general, we should only use these prefixes in the issue title. |
| 40 | + |
| 41 | + * [BUG] |
| 42 | + * [FEATURE REQ] |
| 43 | + * [QUESTION] |
| 44 | + * [QUERY] |
| 45 | + * [Epic] |
| 46 | + |
| 47 | +**Some bad examples**: |
| 48 | + |
| 49 | +* Delete set_identifier_uris.sh |
| 50 | + |
| 51 | + * https://github.com/Azure/azure-sdk-for-java/issues/27766 |
| 52 | + * This is just too short, and no one would understand what this is for |
| 53 | + * Delete unneeded set_identifier_uris.sh from azure-spring-samples project" would better |
| 54 | + |
| 55 | +* Spring App Configuration |
| 56 | + |
| 57 | + * https://github.com/Azure/azure-sdk-for-java/issues/21772 |
| 58 | + * Same as the first one; it just doesn't provide much information. |
| 59 | + * [Epic] Improve Spring App Configuration |
| 60 | + |
| 61 | +* [Enhance Spring integration for storage]Support AppendBlobResource and PageableBlobResource in azure-spring-cloud-storage |
| 62 | + |
| 63 | + * https://github.com/Azure/azure-sdk-for-java/issues/21461 |
| 64 | + |
| 65 | + * Non-standard prefix and seems not much useful |
| 66 | + |
| 67 | + * [FEATURE REQ]Support Spring's AppendBlobResource and PageableBlobResource API in azure-spring-cloud-storage |
| 68 | + |
| 69 | +* resource-server (Write sample about AAD B2C + spring-security + web-flux) |
| 70 | + |
| 71 | + * https://github.com/Azure/azure-sdk-for-java/issues/26333 |
| 72 | + |
| 73 | + * This is not a valid sentence, and I can't tell what this issue wants to do. |
| 74 | + |
| 75 | +* [QUERY] should we consider fix the vulnerability hinted by the spot bug plugin in IDEA |
| 76 | + |
| 77 | + * https://github.com/Azure/azure-sdk-for-java/issues/27194 |
| 78 | + * This is a misunderstanding about the issue type. This should be more of a feature request than a query. |
| 79 | + |
| 80 | +* [FEATURE REQ] Azure Messaging Listener Support Reference Doc |
| 81 | + |
| 82 | + * https://github.com/Azure/azure-sdk-for-java/issues/26999 |
| 83 | + * Can't understand what this issue wants |
| 84 | + |
| 85 | +**Issue Description** |
| 86 | + |
| 87 | +First and foremost, you should NEVER create an issue without a description of this issue or throw two or three words no one would understand, like this one https://github.com/Azure/azure-sdk-for-java/issues/26333. Just gave an 'as subject'. |
| 88 | + |
| 89 | +* The issue's description should stick to the following structure: |
| 90 | + |
| 91 | + Context: explain the conditions which led you to write this issue. |
| 92 | + |
| 93 | + For example: “Since we’ve moved to the latest version of Express.js, we’ve experienced a few performance issues (#14 and #15) on production.” |
| 94 | + |
| 95 | +* Problem or idea: the context should lead to something, an idea, or a problem you’re facing. |
| 96 | + |
| 97 | + For example: “We’ve had no way of easily seeing the performance impact before releasing our changes to production.” |
| 98 | + |
| 99 | + |
| 100 | + |
| 101 | +* Solution or next step: this is where you move forward. You can engage others (request feedback), assign somebody else to the issue, or simply leave it for further investigation. Still, you absolutely need to propose a next step towards solving the issue. |
| 102 | + |
| 103 | +**Formatting** |
| 104 | + |
| 105 | +A well-formatted issue is easier to read, which helps the reader to focus and understand the content. This is another way to improve the quality of our issues. |
| 106 | + |
| 107 | +Markdown (https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) is very simple to learn. |
| 108 | + |
| 109 | + |
| 110 | + |
| 111 | +* Links — Include links to the specific application views you’re describing. |
| 112 | +* Screenshots — A picture is worth 1,000 words (a GIF is worth 1,000,000). A screenshot can help clarify the issue you’re seeing. |
| 113 | +* @me — If you know certain people should be alerted, be sure to mention them in the issue. |
| 114 | + |
| 115 | +### Issue Label |
| 116 | +We use the label in many places, and ensuring the issue/pull request has the right labels is critical for our daily project management. |
| 117 | + |
| 118 | +We should make sure: |
| 119 | + |
| 120 | +1. Issues / PRs created by ourselves have the correct label |
| 121 | + |
| 122 | +1. Correct issues during our daily issue triage |
| 123 | + |
| 124 | +In the meanwhile, we should investigate how to leverage GitHub actions to automate this work `TODO add issue link`. |
| 125 | + |
| 126 | +For every issue / PR, it should contain these kinds of labels: `{mandatory labels}` + `{issue type label}` + `{area labels}` |
| 127 | + |
| 128 | +* **Mandatory** – All Spring related issues / PRs MUST have ALL of the following labels |
| 129 | + |
| 130 | + * Client |
| 131 | + * Azure-spring |
| 132 | + |
| 133 | +* **Issue Type Labels** – All Spring-related issues / PRs MUST have ONE of the following labels since we only have three types of issues. |
| 134 | + |
| 135 | + * Feature-request |
| 136 | + * Bug |
| 137 | + * Question |
| 138 | + |
| 139 | +* **Area Labels** – Any Spring-related issues / PRs may belong to an area, for example, docs or samples related, or an EventHub bug, etc., then it should be labeled with the area label. Please note this is a FIXED list. Please DO NOT create new ones without talking to your lead first. |
| 140 | + |
| 141 | + * Azure-spring-bi TODO – we should probably avoid making BI-related public, using internal ADO to track BI issues. |
| 142 | + * Azure-spring-docs |
| 143 | + * Azure-spring-sample |
| 144 | + * Azure-spring-aad |
| 145 | + * Azure-spring-eventhubs |
| 146 | + * Azure-spring-servicebus |
| 147 | + * Azure-spring-storage |
| 148 | + |
| 149 | +### GitHub Project |
| 150 | + |
| 151 | +When you create a GitHub issue or do issue triage, ensure the issue is added to the Spring Cloud Azure GitHub project(https://github.com/orgs/Azure/projects/94/views/1). |
| 152 | + |
| 153 | +We may get this done automatically in the future, but before we get there, please make sure that manually. |
| 154 | + |
| 155 | +### GitHub Issue Milestone |
| 156 | + |
| 157 | +In general, all newly created issues should be put into the backlog. |
| 158 | + |
| 159 | +We don’t want to have new issues interrupt our sprint planning. |
| 160 | + |
| 161 | +If there is something urgent request happening, talk to your lead or scrum master first. |
| 162 | + |
| 163 | +### GitHub Issue Priority |
| 164 | + |
| 165 | +If you don't know the priority, just leave it blank, do not modify this without talk to your lead or scrum first. |
| 166 | + |
| 167 | +To keep things simple, we use [0-3] to prioritize our issues. |
| 168 | + |
| 169 | + * 0 – Means this issue MUST be resolved within the current sprint |
| 170 | + * 1 – Means this issue SHOULD be resolved within the current sprint, or it will be promoted to P-0 in the next sprint |
| 171 | + * 2 – Means this issue SHOULD be resolved within the current semester |
| 172 | + * 3 – This means this issue will NOT be considered in the current semester |
| 173 | + |
| 174 | +An issue with an empty priority field means one is not triaged yet. |
| 175 | + |
| 176 | +### GitHub Issue Workflow |
| 177 | + |
| 178 | +Again, we use GitHub issues for communication and collaboration, not only inside the team but outside as well. |
| 179 | + |
| 180 | +We expect you to update the progress and information on the GitHub issue you are working on. |
| 181 | + |
| 182 | +For example, if you're working on an investigation issue like "Investigate how to support OpenTelemetry in Azure Spring Cloud" |
| 183 | + |
| 184 | +**You should NEVER** : |
| 185 | + |
| 186 | +1. Close the issue after a couple of days or weeks without anything |
| 187 | +2. Close the issue after a couple of days or weeks with a link to your findings. |
| 188 | + |
| 189 | +**What we expect**: |
| 190 | + |
| 191 | +When you start to work on this issue, keep updating it with your plan/thoughts/findings/references, then provide an investigation with a conclusion about this issue and close it. |
| 192 | + |
0 commit comments