From 85f565b52d38831a74470ed16d5855a43e41e1b4 Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Wed, 30 Oct 2024 19:30:55 +0530 Subject: [PATCH 1/6] Added the first bits intoduction and labelling issues --- docs/contributing/triaging.md | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 docs/contributing/triaging.md diff --git a/docs/contributing/triaging.md b/docs/contributing/triaging.md new file mode 100644 index 00000000..4cfe471b --- /dev/null +++ b/docs/contributing/triaging.md @@ -0,0 +1,8 @@ +## Introduction + +Effective issue management is crucial for maintaining a streamlined development workflow. This document outlines the guidelines for issue labeling and management in GitHub, ensuring clarity, consistency, and efficiency. By clearly defining the roles of various labels, understanding how to link and use them, and distinguishing between discussions and issues, this guide aims to enhance the collaboration and productivity of our development team. + +## Labeling Issues + +Labeling issues effectively is crucial for maintaining clarity and organization within your project. Each label should provide clear information about the nature and status of an issue, making it easier to prioritize and address. Here’s a breakdown of how to label issues in GitHub and the purpose each label serves. + From f77fad7377eb5f6b3edb752bd09483ae5f8f35a6 Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Thu, 31 Oct 2024 17:44:51 +0530 Subject: [PATCH 2/6] Added all the sections as provided in the issue description --- docs/contributing/triaging.md | 125 +++++++++++++++++++++++++++++++++- 1 file changed, 123 insertions(+), 2 deletions(-) diff --git a/docs/contributing/triaging.md b/docs/contributing/triaging.md index 4cfe471b..1fe9ffd3 100644 --- a/docs/contributing/triaging.md +++ b/docs/contributing/triaging.md @@ -1,8 +1,129 @@ ## Introduction -Effective issue management is crucial for maintaining a streamlined development workflow. This document outlines the guidelines for issue labeling and management in GitHub, ensuring clarity, consistency, and efficiency. By clearly defining the roles of various labels, understanding how to link and use them, and distinguishing between discussions and issues, this guide aims to enhance the collaboration and productivity of our development team. +Effective issue management is crucial for maintaining a streamlined development workflow. This document outlines the guidelines for issue labeling and management in GitHub, ensuring clarity, consistency, and efficiency. By clearly defining the roles of various labels and understanding how to link and use them, and distinguishing between discussions and issues, this guide aims to enhance the collaboration and productivity of our development team. ## Labeling Issues -Labeling issues effectively is crucial for maintaining clarity and organization within your project. Each label should provide clear information about the nature and status of an issue, making it easier to prioritize and address. Here’s a breakdown of how to label issues in GitHub and the purpose each label serves. +Labeling issues effectively is crucial for maintaining clarity and organization within the project. Each label should provide clear information about the nature and status of an issue, making it easier to prioritize and address. Here’s a breakdown of how to label issues in GitHub and the purpose each label serves. + +### Issue Types + +- **bug**: Use for issues that identify bugs causing incorrect or unexpected behavior. + +- **dependencies**: Use this label for issues concerning dependencies. + +- **documentation**: Use this label for issues related to documentation. + +- **library**: Use this label for issues related to core libraries or preparations for future plugin impacts. + + +### Requests and Feedback + +- **enhancement**: Use this label for requests for new features or improvements to existing functionalities. + +- **feedback**: Use this label for issues where feedback is requested from the team or our community. + +- **help**: Use this label for issues where additional help or contributions are needed. + + +### Special Labels + +- **automation**: Use this label for issues related to the CI/CD pipeline or automation + +- **duplicate**: Use this label for issues that are duplicates of existing ones. + +- **good first issue** : Use this label to highlight issues good for newcomers who want to contribute to Earthaccess. + +- **hackathon**: Use this label for issues to be discussed during hackdays. + +- **wontfix**: Use this label for issues that won’t be addressed or fixed. + + +## Linking Labels in GitHub Markdown + +When referencing a label in a GitHub issue or discussion, it is will be useful to link to the label page to provide additional context and help others community members to quickly understand the issue's category. + +### Syntax + +To link to a label in GitHub Markdown, use the following syntax: + +``` +[label name](https://github.com/username/repository/labels/label-name) +``` + +### Example + +For example, to link to the "hackathon" label in the nsidc/earthaccess repository, you would use the following syntax: + + +``` +[hackathon](https://github.com/nsidc/earthaccess/labels/hackathon) +``` + +!!! tip + When linking to labels, it is a good practice to use the label name as the link text, as shown in the example above. This makes it clear to others what label is being referenced, and helps to avoid confusion. + +## Close Issue as Not Planned + +This section will cover the guidelines for when to use the "Close Issue as Not Planned" label, and how to handle issues that are not planned or feasible. + +### Overview + +The "Close Issue as Not Planned" label is used to indicate that an issue is not planned or feasible to be addressed. + +### When to Use This Label + +Use the "Close Issue as Not Planned" label when: + +- An issue is not aligned with the project's goals or priorities +- An issue is not feasible to be addressed due to technical or resource constraints +- An issue is a duplicate of an existing issue that has already been addressed + +!!! tip + When closing an issue as not planned, keep the following best practices in mind: + + * Provide a clear explanation as to why the issue is not planned or feasible + * Offer alternative solutions or workarounds, if possible + * Link to relevant documentation or resources, if applicable + +### Discussions vs Issues + +This section would cover the guidelines for when to use discussions versus issues, and how to migrate between them. + +### Overview +Discussions and issues are two different features in GitHub that serve distinct purposes. + +### Discussions + +Discussions are used for: + +- Brainstorming and idea generation. +- Feature requests and feedback. +- General questions and topics. + +### Issues + +Issues are used for: + +- Reporting bugs and errors. +- Tracking progress on specific tasks or projects. +- Requesting changes or improvements. + + +#### When to Migrate + +**Migrate a discussion to an issue when:** + +* Specific task or project is identified. +* A* bug or error is reported. +* A change or improvement is requested. + +**Migrate an issue to a discussion when:** + +* The issue is a feature request or idea +* The issue is a general question or topic +* The issue is not specific or actionable + + + From 4b82dbf0d87975e4d06d1863a365965b597501c2 Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Fri, 13 Dec 2024 20:36:57 +0530 Subject: [PATCH 3/6] Added issue pr workflow diagram --- docs/contributing/triaging.md | 94 ++++++++++++++++++++++------------- mkdocs.yml | 9 +++- 2 files changed, 68 insertions(+), 35 deletions(-) diff --git a/docs/contributing/triaging.md b/docs/contributing/triaging.md index 1fe9ffd3..a433ac92 100644 --- a/docs/contributing/triaging.md +++ b/docs/contributing/triaging.md @@ -1,10 +1,10 @@ -## Introduction -Effective issue management is crucial for maintaining a streamlined development workflow. This document outlines the guidelines for issue labeling and management in GitHub, ensuring clarity, consistency, and efficiency. By clearly defining the roles of various labels and understanding how to link and use them, and distinguishing between discussions and issues, this guide aims to enhance the collaboration and productivity of our development team. +With constant influx of new issues, it's quite essential to prioritize and categorize them efficiently to ensure that the most imporatnt problems are addressed promptly. This document outlines our approach to triaging issues on GitHub, including guidelines for labeling and resolving issues, as well as best practices for maintaining a well-organized and up-to-date issue tracker. ## Labeling Issues -Labeling issues effectively is crucial for maintaining clarity and organization within the project. Each label should provide clear information about the nature and status of an issue, making it easier to prioritize and address. Here’s a breakdown of how to label issues in GitHub and the purpose each label serves. +When labeling an issue, choose the label that best describes the issue. Using labels consistently and accurately ensures that issues are easily trackable. + ### Issue Types @@ -41,7 +41,7 @@ Labeling issues effectively is crucial for maintaining clarity and organization ## Linking Labels in GitHub Markdown -When referencing a label in a GitHub issue or discussion, it is will be useful to link to the label page to provide additional context and help others community members to quickly understand the issue's category. +When referencing a label in a GitHub issue or discussion, it will be useful to link to the label page to provide additional context and help other members to quickly understand the issue's category. ### Syntax @@ -55,7 +55,6 @@ To link to a label in GitHub Markdown, use the following syntax: For example, to link to the "hackathon" label in the nsidc/earthaccess repository, you would use the following syntax: - ``` [hackathon](https://github.com/nsidc/earthaccess/labels/hackathon) ``` @@ -67,33 +66,25 @@ For example, to link to the "hackathon" label in the nsidc/earthaccess repositor This section will cover the guidelines for when to use the "Close Issue as Not Planned" label, and how to handle issues that are not planned or feasible. -### Overview - -The "Close Issue as Not Planned" label is used to indicate that an issue is not planned or feasible to be addressed. - -### When to Use This Label +### When to Use This Label? Use the "Close Issue as Not Planned" label when: -- An issue is not aligned with the project's goals or priorities -- An issue is not feasible to be addressed due to technical or resource constraints -- An issue is a duplicate of an existing issue that has already been addressed +- An issue is not aligned with the project's goals or priorities. +- An issue is not feasible to be addressed due to technical or resource constraints. +- An issue is a duplicate of an existing issue that has already been addressed. -!!! tip - When closing an issue as not planned, keep the following best practices in mind: +When closing an issue as not planned, keep the following best practices in mind: - * Provide a clear explanation as to why the issue is not planned or feasible - * Offer alternative solutions or workarounds, if possible - * Link to relevant documentation or resources, if applicable +- Provide a clear explanation as to why the issue is not planned or feasible. +- Offer alternative solutions or workarounds, if possible. +- Link to relevant documentation or resources, if applicable. -### Discussions vs Issues +## Discussions vs Issues This section would cover the guidelines for when to use discussions versus issues, and how to migrate between them. -### Overview -Discussions and issues are two different features in GitHub that serve distinct purposes. - -### Discussions +### What are Discussions? Discussions are used for: @@ -101,7 +92,7 @@ Discussions are used for: - Feature requests and feedback. - General questions and topics. -### Issues +### What are Issues? Issues are used for: @@ -109,20 +100,55 @@ Issues are used for: - Tracking progress on specific tasks or projects. - Requesting changes or improvements. +### When to Migrate + +Migrate a discussion to an issue when: + +- A specific task is identified. +- A bug or error is reported. +- A change or improvement is requested. + +Migrate an issue to a discussion when: + +- The issue is a feature request or idea. +- The issue is a general question or topic. +- The issue is not specific or actionable. + +## Issue Triaging Workflow + +``` mermaid + +flowchart TD + %%{init: {"flowchart": {"htmlLabels": false}} }%% + classDef default font-size:32pt; + start{"`Followed + issue + template?`"} + start --NO --> close1[Close and ask to + follow template] + %% Link Color %% + linkStyle 0 stroke:black,stroke-width:2px,font-size:36pt; + start -- YES --> dupe{Is duplicate?} + dupe -- YES --> close2[Close and point\nto duplicate] + dupe -- NO --> repro{Has proper\nreproduction?} + repro -- NO --> close3[Label: 'needs reproduction'\nbot will auto close if no update\nhas been made in 3 days] + repro -- YES --> real{Is actually a bug?} + real -- NO --> intended{Is the intended\nbehaviour?} + intended -- YES --> explain[Explain and close\npoint to docs if needed] + intended -- NO --> open[Keep open for discussion\nRemove 'pending triage' label] + real -- YES --> real2["1. Remove 'pending triage' label\n2. Add related feature label if\napplicable (e.g. 'feat: ssr')\n3. Add priority and meta labels (see below)"] + real2 --> unusable{Does the\nbug make Vite\nunusable?} + unusable -- YES --> maj{Does the bug\naffect the majority\nof Vite users?} + maj -- YES --> p5[p5: urgent] + maj -- NO --> p4[p4: important] + unusable -- NO --> workarounds{Are there\nworkarounds for\nthe bug?} + workarounds -- NO --> p3[p3: minor bug] + workarounds -- YES --> p2[p2: edge case\nhas workaround] -#### When to Migrate - -**Migrate a discussion to an issue when:** +``` -* Specific task or project is identified. -* A* bug or error is reported. -* A change or improvement is requested. -**Migrate an issue to a discussion when:** -* The issue is a feature request or idea -* The issue is a general question or topic -* The issue is not specific or actionable diff --git a/mkdocs.yml b/mkdocs.yml index 1eb56098..d69d5596 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,6 +33,7 @@ extra_css: plugins: - search + - mermaid2 - mkdocstrings: default_handler: python handlers: @@ -56,6 +57,7 @@ plugins: - "tutorials/dask.ipynb" - "**/.ipynb_checkpoints/*" + nav: - "What is earthaccess?": "index.md" - "Quick start": "quick-start.md" @@ -67,6 +69,7 @@ nav: - "Maintainers Guide": "contributing/maintainers-guide.md" - "Code of Conduct": "contributing/code-of-conduct.md" - "Contributing naming convention": "contributing/naming-convention.md" + - "Triaging" : "contributing/triaging.md" - "Resources": "resources.md" - USER GUIDE: - "user_guide/index.md" @@ -119,7 +122,11 @@ markdown_extensions: anchor_linenums: true - pymdownx.inlinehilite - pymdownx.snippets - - pymdownx.superfences + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:mermaid2.fence_mermaid_custom - pymdownx.tabbed: alternate_style: true From ae0e833ac623c38347340dfb4eebbcdf906cf3d9 Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Sat, 14 Dec 2024 20:28:07 +0530 Subject: [PATCH 4/6] Made some adjustments to the flowchart in the context of earthaccess --- docs/contributing/triaging.md | 39 ++++++++++++++++++----------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/docs/contributing/triaging.md b/docs/contributing/triaging.md index a433ac92..13e90295 100644 --- a/docs/contributing/triaging.md +++ b/docs/contributing/triaging.md @@ -124,26 +124,27 @@ flowchart TD start{"`Followed issue template?`"} - start --NO --> close1[Close and ask to - follow template] + start ==NO==> close1[Change + to draft and ask to follow template] + start == YES ==> dupe{Is duplicate?} + dupe == YES ==> close2[Close and pointto duplicate] + dupe == NO ==> repro{Has proper reproduction?} + repro == NO ==> close3[Label: 'needs reproduction' bot will auto close if no update has been made in 3 days] + repro == YES ==> real{Is actually a bug?} + real == NO ==> intended{Is the intended behaviour?} + intended == YES ==> explain[Explain and close point to docs if needed] + intended == NO ==> open[Keep open for discussion Remove 'pending triage' label] + real == YES ==> real2["1. Remove 'pending triage' label 2. Add related feature label if applicable (e.g. 'feat: ssr') 3. Add priority and meta labels (see below)"] + real2 ==> unusable{Does the bug make earthaccess unusable?} + unusable == YES ==> maj{Does the bug affect the majority of earthaccess users?} + maj == YES ==> p5[p5: urgent] + maj == NO ==> p4[p4: important] + unusable == NO ==> workarounds{Are there workarounds for the bug?} + workarounds == NO ==> p3[p3: minor bug] + workarounds == YES ==> p2[p2: edge case has workaround] + %% Link Color %% - linkStyle 0 stroke:black,stroke-width:2px,font-size:36pt; - start -- YES --> dupe{Is duplicate?} - dupe -- YES --> close2[Close and point\nto duplicate] - dupe -- NO --> repro{Has proper\nreproduction?} - repro -- NO --> close3[Label: 'needs reproduction'\nbot will auto close if no update\nhas been made in 3 days] - repro -- YES --> real{Is actually a bug?} - real -- NO --> intended{Is the intended\nbehaviour?} - intended -- YES --> explain[Explain and close\npoint to docs if needed] - intended -- NO --> open[Keep open for discussion\nRemove 'pending triage' label] - real -- YES --> real2["1. Remove 'pending triage' label\n2. Add related feature label if\napplicable (e.g. 'feat: ssr')\n3. Add priority and meta labels (see below)"] - real2 --> unusable{Does the\nbug make Vite\nunusable?} - unusable -- YES --> maj{Does the bug\naffect the majority\nof Vite users?} - maj -- YES --> p5[p5: urgent] - maj -- NO --> p4[p4: important] - unusable -- NO --> workarounds{Are there\nworkarounds for\nthe bug?} - workarounds -- NO --> p3[p3: minor bug] - workarounds -- YES --> p2[p2: edge case\nhas workaround] + linkStyle default stroke:black,stroke-width:2px,font-size:24pt; ``` From 8a2c4e7604d50cad0ee5b2c836d6d4df62484073 Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Sun, 15 Dec 2024 12:12:20 +0530 Subject: [PATCH 5/6] Initial triaging draft --- CHANGELOG.md | 6 ++++++ docs/contributing/triaging.md | 2 +- mkdocs.yml | 2 +- 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ec21ddb6..f66e4621 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,11 @@ and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html) ## [Unreleased] +### Added + +- Added triaging document([#754](https://github.com/nsidc/earthaccess/issues/754)) + ([@Sherwin-14](https://github.com/Sherwin-14)) + ## [v0.12.0] - 2024-11-13 ### Changed @@ -31,6 +36,7 @@ and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html) integration tests ([#824](https://github.com/nsidc/earthaccess/issues/824)) ([@chuckwondo](https://github.com/chuckwondo)) + ### Removed - The `scripts/integration-test.sh` script has been removed in favor of the `integration-tests` nox session. diff --git a/docs/contributing/triaging.md b/docs/contributing/triaging.md index 13e90295..b71ae606 100644 --- a/docs/contributing/triaging.md +++ b/docs/contributing/triaging.md @@ -127,7 +127,7 @@ flowchart TD start ==NO==> close1[Change to draft and ask to follow template] start == YES ==> dupe{Is duplicate?} - dupe == YES ==> close2[Close and pointto duplicate] + dupe == YES ==> close2[Close and point to duplicate] dupe == NO ==> repro{Has proper reproduction?} repro == NO ==> close3[Label: 'needs reproduction' bot will auto close if no update has been made in 3 days] repro == YES ==> real{Is actually a bug?} diff --git a/mkdocs.yml b/mkdocs.yml index d69d5596..22fa9337 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,7 +69,7 @@ nav: - "Maintainers Guide": "contributing/maintainers-guide.md" - "Code of Conduct": "contributing/code-of-conduct.md" - "Contributing naming convention": "contributing/naming-convention.md" - - "Triaging" : "contributing/triaging.md" + - "Triaging Doc" : "contributing/triaging.md" - "Resources": "resources.md" - USER GUIDE: - "user_guide/index.md" From a7a182c82f0b5881b42d4c22f6340297d46a92a8 Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Sun, 15 Dec 2024 12:22:58 +0530 Subject: [PATCH 6/6] Removed extra spaces --- CHANGELOG.md | 2 +- docs/contributing/triaging.md | 21 +++++++-------------- mkdocs.yml | 10 +++++----- 3 files changed, 13 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f66e4621..2437b3c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html) - Added triaging document([#754](https://github.com/nsidc/earthaccess/issues/754)) ([@Sherwin-14](https://github.com/Sherwin-14)) + ([@mfisher87](https://github.com/mfisher87)) ## [v0.12.0] - 2024-11-13 @@ -36,7 +37,6 @@ and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html) integration tests ([#824](https://github.com/nsidc/earthaccess/issues/824)) ([@chuckwondo](https://github.com/chuckwondo)) - ### Removed - The `scripts/integration-test.sh` script has been removed in favor of the `integration-tests` nox session. diff --git a/docs/contributing/triaging.md b/docs/contributing/triaging.md index b71ae606..9bb3b0e5 100644 --- a/docs/contributing/triaging.md +++ b/docs/contributing/triaging.md @@ -47,7 +47,7 @@ When referencing a label in a GitHub issue or discussion, it will be useful to To link to a label in GitHub Markdown, use the following syntax: -``` +``` [label name](https://github.com/username/repository/labels/label-name) ``` @@ -55,7 +55,7 @@ To link to a label in GitHub Markdown, use the following syntax: For example, to link to the "hackathon" label in the nsidc/earthaccess repository, you would use the following syntax: -``` +``` [hackathon](https://github.com/nsidc/earthaccess/labels/hackathon) ``` @@ -80,7 +80,7 @@ When closing an issue as not planned, keep the following best practices in mind: - Offer alternative solutions or workarounds, if possible. - Link to relevant documentation or resources, if applicable. -## Discussions vs Issues +## Discussions vs Issues This section would cover the guidelines for when to use discussions versus issues, and how to migrate between them. @@ -100,7 +100,7 @@ Issues are used for: - Tracking progress on specific tasks or projects. - Requesting changes or improvements. -### When to Migrate +### When to Migrate Migrate a discussion to an issue when: @@ -121,10 +121,10 @@ Migrate an issue to a discussion when: flowchart TD %%{init: {"flowchart": {"htmlLabels": false}} }%% classDef default font-size:32pt; - start{"`Followed - issue + start{"`Followed + issue template?`"} - start ==NO==> close1[Change + start ==NO==> close1[Change to draft and ask to follow template] start == YES ==> dupe{Is duplicate?} dupe == YES ==> close2[Close and point to duplicate] @@ -147,10 +147,3 @@ flowchart TD linkStyle default stroke:black,stroke-width:2px,font-size:24pt; ``` - - - - - - - diff --git a/mkdocs.yml b/mkdocs.yml index 22fa9337..d197f381 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,7 +57,6 @@ plugins: - "tutorials/dask.ipynb" - "**/.ipynb_checkpoints/*" - nav: - "What is earthaccess?": "index.md" - "Quick start": "quick-start.md" @@ -69,7 +68,7 @@ nav: - "Maintainers Guide": "contributing/maintainers-guide.md" - "Code of Conduct": "contributing/code-of-conduct.md" - "Contributing naming convention": "contributing/naming-convention.md" - - "Triaging Doc" : "contributing/triaging.md" + - "Triaging Doc": "contributing/triaging.md" - "Resources": "resources.md" - USER GUIDE: - "user_guide/index.md" @@ -124,9 +123,10 @@ markdown_extensions: - pymdownx.snippets - pymdownx.superfences: custom_fences: - - name: mermaid - class: mermaid - format: !!python/name:mermaid2.fence_mermaid_custom + - name: mermaid + class: mermaid + format: !!python/name:mermaid2.fence_mermaid_custom + - pymdownx.tabbed: alternate_style: true