docs: revamp issue templates

echasnovski · echasnovski · commit 3f3a4a260931 · 2025-01-02T18:05:12.000+02:00
diff --git a/.github/DISCUSSION_TEMPLATE/q-a.yml b/.github/DISCUSSION_TEMPLATE/q-a.yml
@@ -0,0 +1,69 @@
+labels: [question]
+body:
+  - type: checkboxes
+    id: guidelines
+    attributes:
+      label: Contributing guidelines
+      options:
+      - label: I have read [CODE_OF_CONDUCT.md](https://github.com/echasnovski/mini.nvim/blob/main/CODE_OF_CONDUCT.md)
+        required: true
+  - type: dropdown
+    id: module
+    attributes:
+      label: "Module(s)"
+      description: "Choose one or several modules this question is related to"
+      multiple: true
+      options:
+        - mini.ai
+        - mini.align
+        - mini.animate
+        - mini.base16
+        - mini.basics
+        - mini.bracketed
+        - mini.bufremove
+        - mini.clue
+        - mini.colors
+        - mini.comment
+        - mini.completion
+        - mini.cursorword
+        - mini.deps
+        - mini.diff
+        - mini.doc
+        - mini.extra
+        - mini.files
+        - mini.fuzzy
+        - mini.git
+        - mini.hipatterns
+        - mini.hues
+        - mini.icons
+        - mini.indentscope
+        - mini.jump
+        - mini.jump2d
+        - mini.map
+        - mini.misc
+        - mini.move
+        - mini.notify
+        - mini.operators
+        - mini.pairs
+        - mini.pick
+        - mini.sessions
+        - mini.snippets
+        - mini.splitjoin
+        - mini.starter
+        - mini.statusline
+        - mini.surround
+        - mini.tabline
+        - mini.test
+        - mini.trailspace
+        - mini.visits
+        - none of the above
+        - all of the above
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: "Question"
+    validations:
+      required: true
+
diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml
@@ -1,51 +1,129 @@
 name: Bug report
-description: Report a problem
+description: Report a problem with the existing module(s)
 labels: [bug]
 body:
   - type: checkboxes
+    id: guidelines
     attributes:
       label: Contributing guidelines
       options:
       - label: I have read [CONTRIBUTING.md](https://github.com/echasnovski/mini.nvim/blob/main/CONTRIBUTING.md)
         required: true
       - label: I have read [CODE_OF_CONDUCT.md](https://github.com/echasnovski/mini.nvim/blob/main/CODE_OF_CONDUCT.md)
         required: true
-      - label: I have updated 'mini.nvim' to latest version
+      - label: I have updated 'mini.nvim' to latest version of the `main` branch
         required: true
-  - type: input
+  - type: dropdown
+    id: module
     attributes:
       label: "Module(s)"
-      description: "List one or several modules this bug is coming from"
-    validations:
-      required: true
-  - type: textarea
-    attributes:
-      label: "Description"
-      description: "A short description of a problem"
+      description: "Choose one or several modules the problem is related to"
+      multiple: true
+      options:
+        - mini.ai
+        - mini.align
+        - mini.animate
+        - mini.base16
+        - mini.basics
+        - mini.bracketed
+        - mini.bufremove
+        - mini.clue
+        - mini.colors
+        - mini.comment
+        - mini.completion
+        - mini.cursorword
+        - mini.deps
+        - mini.diff
+        - mini.doc
+        - mini.extra
+        - mini.files
+        - mini.fuzzy
+        - mini.git
+        - mini.hipatterns
+        - mini.hues
+        - mini.icons
+        - mini.indentscope
+        - mini.jump
+        - mini.jump2d
+        - mini.map
+        - mini.misc
+        - mini.move
+        - mini.notify
+        - mini.operators
+        - mini.pairs
+        - mini.pick
+        - mini.sessions
+        - mini.snippets
+        - mini.splitjoin
+        - mini.starter
+        - mini.statusline
+        - mini.surround
+        - mini.tabline
+        - mini.test
+        - mini.trailspace
+        - mini.visits
     validations:
       required: true
-  - type: input
+  - type: dropdown
+    id: nvim-version
     attributes:
       label: "Neovim version"
-      description: "Something like `0.5`, `0.5.1`, Neovim nightly (please, include latest commit)"
+      description: "Choose the latest Neovim version on which you can reproduce the problem"
+      multiple: false
+      options:
+        - 0.8.x
+        - 0.9.x
+        - 0.10.x
+        - 0.11 (!at least latest Nightly build!)
+      default: 2
     validations:
       required: true
   - type: textarea
+    id: description
     attributes:
-      label: "Steps to reproduce"
-      description: "Steps to reproduce using as minimal config as possible"
-      value: |
-        1. `nvim -nu minimal.lua`
-        2. ...
+      label: "Description"
+      description: "A short description of a problem; include expected behavior"
     validations:
       required: true
   - type: textarea
+    id: reproduction
     attributes:
-      label: "Expected behavior"
-      description: "A description of behavior you expected"
-  - type: textarea
-    attributes:
-      label: "Actual behavior"
-      description: "A description of behavior you observed (feel free to include images, gifs, etc.)"
+      label: "Reproduction"
+      description: "Steps to reproduce the issue. Suggested steps involve creating an independent config from scratch. If can not reproduce like this, please ask a usage question first."
+      value: |
+        1. Create separate 'nvim-repro' config directory:
+            - '~/.config/nvim-repro/' on Unix
+            - '~/AppData/Local/nvim-repro/' on Windows
+
+        2. Inside 'nvim-repro' directory create a file named 'init.lua'.
+           Populate it with the following content:
+
+            ```lua
+            -- Clone latest 'mini.nvim' (requires Git CLI installed)
+            vim.cmd('echo "Installing `mini.nvim`" | redraw')
+            local mini_path = vim.fn.stdpath('data') .. '/site/pack/deps/start/mini.nvim'
+            local clone_cmd = { 'git', 'clone', '--depth=1', 'https://github.com/echasnovski/mini.nvim', mini_path }
+            vim.fn.system(clone_cmd)
+            vim.cmd('echo "`mini.nvim` is installed" | redraw')
+
+            -- Make sure 'mini.nvim' is available
+            vim.cmd('packadd mini.nvim')
+            require('mini.deps').setup()
+
+            -- Add extra setup steps needed to reproduce the behavior
+            -- Use `MiniDeps.add('user/repo')` to install another plugin from GitHub
+            ```
+
+        3. Run `NVIM_APPNAME=nvim-repro nvim` (i.e. execute `nvim` with `NVIM_APPNAME` environment variable set to "nvim-repro").
+           Wait for all dependencies to install.
+
+        4. Replace this with description of interactive reproduction steps along with the behavior you observe.
+           Feel free to include images/videos/etc, this helps a lot.
+
+        Note: after reporting the issue, it is safe (and even recommended for
+        cleaner future issues) to remove 'nvim-repro' config from the system:
+        - Delete config directory ('~/.config/nvim-repro' on Unix).
+        - Delete data directory ('~/.local/share/nvim-repro' on Unix).
+        - Delete state directory ('~/.local/state/nvim-repro' on Unix).
     validations:
       required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -1 +1,5 @@
-blank_issues_enabled: true
+blank_issues_enabled: false
+contact_links:
+  - name: Question
+    url: https://github.com/echasnovski/mini.nvim/discussions/new?category=q-a
+    about: Ask about configuration and usage of 'mini.nvim'
diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml
@@ -1,22 +1,70 @@
 name: Feature request
-description: Describe a feature you want to see
+description: Describe a new feature you would like to see
 labels: [feature-request]
 body:
   - type: checkboxes
+    id: guidelines
     attributes:
       label: Contributing guidelines
       options:
       - label: I have read [CONTRIBUTING.md](https://github.com/echasnovski/mini.nvim/blob/main/CONTRIBUTING.md)
         required: true
       - label: I have read [CODE_OF_CONDUCT.md](https://github.com/echasnovski/mini.nvim/blob/main/CODE_OF_CONDUCT.md)
         required: true
-  - type: input
+  - type: dropdown
+    id: module
     attributes:
       label: "Module(s)"
-      description: "List one or several modules this feature is related to"
+      description: "Choose one or several modules this feature is related to. Choose 'new' for a new module suggestion."
+      multiple: true
+      options:
+        - mini.ai
+        - mini.align
+        - mini.animate
+        - mini.base16
+        - mini.basics
+        - mini.bracketed
+        - mini.bufremove
+        - mini.clue
+        - mini.colors
+        - mini.comment
+        - mini.completion
+        - mini.cursorword
+        - mini.deps
+        - mini.diff
+        - mini.doc
+        - mini.extra
+        - mini.files
+        - mini.fuzzy
+        - mini.git
+        - mini.hipatterns
+        - mini.hues
+        - mini.icons
+        - mini.indentscope
+        - mini.jump
+        - mini.jump2d
+        - mini.map
+        - mini.misc
+        - mini.move
+        - mini.notify
+        - mini.operators
+        - mini.pairs
+        - mini.pick
+        - mini.sessions
+        - mini.snippets
+        - mini.splitjoin
+        - mini.starter
+        - mini.statusline
+        - mini.surround
+        - mini.tabline
+        - mini.test
+        - mini.trailspace
+        - mini.visits
+        - new
     validations:
       required: true
   - type: textarea
+    id: description
     attributes:
       label: "Description"
       description: "A concise and justified description of a feature"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -6,7 +6,9 @@ You can make contributions in the following ways:
 
 - **Mention it** somehow to help reach broader audience. This helps a lot.
 - **Create a GitHub issue**. It can be one of the following types:
-    - **Bug report**. Describe your actions in a reproducible way along with their effect and what you expected should happen. Before making one, please make your best efforts to make sure that it is not an intended behavior (not described in documentation as such).
+    - **Bug report**. Describe your actions in a reproducible way along with their effect and what you expected should happen. Before making one, please make your best efforts to:
+        - Make sure that it is not an intended behavior, i.e. not described in documentation as such.
+        - Make sure that it was not reported before, i.e. there is no bug report already created (no matter open or closed).
     - **Feature request**. A concise and justified description of what one or several modules should be able to do. Before making one, please make your best efforts to make sure that it is not a feature that won't get implemented (these should be described in documentation; for example: block comments in 'mini.comment').
 - **Create a pull request (PR)**. It can be one of the following types:
     - **Code related**. For example, fix a bug or implement a feature. **Before even starting one, please make sure that it is aligned with project vision and goals**. The best way to do so is to receive positive feedback from maintainer on your initiative in one of the GitHub issues (existing or created by you). Please, make sure to regenerate latest help file and that all tests pass (see later sections).
diff --git a/MAINTAINING.md b/MAINTAINING.md
@@ -111,7 +111,8 @@ Begin the process of stopping official support for outdated Neovim version short
     end
     ```
 
-    - Modify CI to not test on Neovim 0.x.
+    - Modify CI to not test on old Neovim version.
+    - Update issue template to not include old Neovim version.
     - Update README and repo description to indicate new oldest supported Neovim version.
     - Wait for a considerable amount of time (at least about a month) *and* a new 'mini.nvim' stable release (so that there is no actual deprecation in the stable release).
 
@@ -121,6 +122,11 @@ Begin the process of stopping official support for outdated Neovim version short
     - Adjust code/comments/documentation that contains any combination of `Neovim{<,<=,=,>=,>}{0.x,0.(x+1)}` (like `Neovim<0.x`, `Neovim>=0.(x+1)`, etc.).
     - Add entry "Stop official support of Neovim 0.x." in 'CHANGELOG.md' at the start of current development version block.
 
+## Reacting to new minor Neovim version
+
+- Modify CI to test on new Neovim version.
+- Update issue template to mention new Neovim version as released one, make it default choice, and bump Nightly version.
+
 ## Adding new config settings
 
 - Add code which uses new setting.
@@ -145,9 +151,13 @@ Begin the process of stopping official support for outdated Neovim version short
 - Add Lua source code in 'lua' directory.
 - Add tests in 'tests' directory. Use 'tests/dir-xxx' name for module-specific non-test helpers.
 - Update 'lua/init.lua' to mention new module: both in initial table of contents and list of modules.
-- Update 'scripts/minidoc.lua' to generate separate help file.
-- Update 'scripts/dual_sync.sh' to include new module.
-- Update 'scripts/dual_release.sh' to include new module.
+- Add new module to the following files:
+    - 'scripts/minidoc.lua' to generate separate help file.
+    - 'scripts/dual_sync.sh' to include new module.
+    - 'scripts/dual_release.sh' to include new module.
+    - '.github/ISSUE_TEMPLATE/bug-report.yml' to be included in a dropdown menu.
+    - '.github/ISSUE_TEMPLATE/feature-request.yml' to be included in a dropdown menu.
+    - '.github/DISCUSSION_TEMPLATE/q-a.yml' to be included in a dropdown menu.
 - Generate help files.
 - Add README to 'readmes' directory. NOTE: comment out mentions of `stable` branch, as it won't work during beta-testing.
 - Update main README to mention new module in table of contents.
