Skip to content

Commit 7f9af3c

Browse files
Copilotnjzjz
Copilot
and
njzjz
committed
Add GitHub Discussion templates with emphasis on reproducible examples
Co-authored-by: njzjz <9496702+njzjz@users.noreply.github.com>
1 parent 18ec156 commit 7f9af3c

6 files changed

Lines changed: 667 additions & 0 deletions

File tree

‎.github/DISCUSSION_TEMPLATE/README.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Discussion Templates
2+
3+
This directory contains GitHub Discussion templates for the DeePMD-kit repository. These templates help guide users to provide comprehensive information when starting discussions, particularly emphasizing the importance of reproducible examples.
4+
5+
## Available Templates
6+
7+
### 1. General Question (`general-question.yml`)
8+
For general questions about DeePMD-kit usage, features, or concepts. Use this when you have a straightforward question that doesn't require extensive troubleshooting.
9+
10+
### 2. Usage Help (`usage-help.yml`)
11+
For detailed help with specific DeePMD-kit usage scenarios. **This template strongly emphasizes providing reproducible examples** to help community members provide effective assistance.
12+
13+
### 3. Ideas and Suggestions (`ideas-suggestions.yml`)
14+
For proposing new features, improvements, or enhancements to DeePMD-kit. Includes sections for use cases, related work, and implementation thoughts.
15+
16+
### 4. Show and Tell (`show-and-tell.yml`)
17+
For sharing projects, research, or achievements using DeePMD-kit. Encourages sharing reproducible information and lessons learned.
18+
19+
### 5. Potential Bug Discussion (`potential-bug.yml`)
20+
For discussing behavior that might be a bug before creating a formal issue. **Emphasizes providing complete reproducible examples** to help confirm whether the behavior is indeed a bug.
21+
22+
## Key Features
23+
24+
All templates are designed to:
25+
- **Encourage reproducible examples**: Each template emphasizes the importance of providing complete, minimal examples that others can reproduce
26+
- Follow the repository's existing style and conventions
27+
- Include appropriate labels for categorization
28+
- Provide clear guidance on what information to include
29+
- Help users structure their discussions effectively
30+
31+
## Usage
32+
33+
When users start a new discussion, they will be presented with these template options. The templates guide them to provide:
34+
35+
- Clear problem descriptions
36+
- Version information
37+
- Reproducible examples with:
38+
- Input files
39+
- Configuration files
40+
- Commands run
41+
- Expected vs actual behavior
42+
- Complete error messages
43+
44+
This addresses the issue mentioned in #4506 where "many discussions do not give reproduced examples."

‎.github/DISCUSSION_TEMPLATE/general-question.yml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
name: General Question
2+
description: Ask a general question about DeePMD-kit usage, features, or concepts
3+
labels: ["question"]
4+
body:
5+
- type: textarea
6+
id: summary
7+
attributes:
8+
label: Summary
9+
description: Please provide a clear and concise description of your question.
10+
placeholder: What would you like to know about DeePMD-kit?
11+
value:
12+
validations:
13+
required: true
14+
- type: input
15+
id: version
16+
attributes:
17+
label: DeePMD-kit Version
18+
description: "What version of DeePMD-kit are you using? Run `dp --version` to check."
19+
placeholder: "e.g., 2.2.7"
20+
validations:
21+
required: false
22+
- type: input
23+
id: backend-version
24+
attributes:
25+
label: Backend and Version
26+
description: "Which backend are you using and what version? (e.g., TensorFlow v2.15.0, PyTorch v2.0.1)"
27+
placeholder: "e.g., TensorFlow v2.15.0"
28+
validations:
29+
required: false
30+
- type: textarea
31+
id: details
32+
attributes:
33+
label: Detailed Description
34+
description: |
35+
Please provide more details about your question. If you're having trouble with specific functionality, please include:
36+
- What you're trying to achieve
37+
- What you've tried so far
38+
- Any relevant configuration or setup details
39+
placeholder: Provide additional context that would help others understand and answer your question.
40+
value:
41+
validations:
42+
required: true
43+
- type: textarea
44+
id: reproducible-example
45+
attributes:
46+
label: Reproducible Example (if applicable)
47+
description: |
48+
If your question relates to specific code, input files, or commands, please provide a minimal reproducible example.
49+
This helps others understand your issue and provide better assistance.
50+
51+
**Please include:**
52+
- Input files (minimal example)
53+
- Commands you're running
54+
- Configuration files
55+
- Expected vs actual behavior
56+
placeholder: |
57+
```bash
58+
# Your commands here
59+
dp train input.json
60+
```
61+
62+
```json
63+
// Your configuration here
64+
{
65+
"model": {...}
66+
}
67+
```
68+
value:
69+
validations:
70+
required: false
71+
- type: textarea
72+
id: additional-info
73+
attributes:
74+
label: Additional Information
75+
description: |
76+
Any additional information, links to documentation you've consulted, or other relevant details.
77+
placeholder: Links, references, or other context that might be helpful.
78+
value:
79+
validations:
80+
required: false

‎.github/DISCUSSION_TEMPLATE/ideas-suggestions.yml‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
name: Ideas and Suggestions
2+
description: Share ideas for new features, improvements, or enhancements to DeePMD-kit
3+
labels: ["idea", "enhancement"]
4+
body:
5+
- type: textarea
6+
id: summary
7+
attributes:
8+
label: Summary
9+
description: Brief summary of your idea or suggestion
10+
placeholder: What's your idea for improving DeePMD-kit?
11+
value:
12+
validations:
13+
required: true
14+
- type: dropdown
15+
id: category
16+
attributes:
17+
label: Category
18+
description: What area does your suggestion relate to?
19+
options:
20+
- New feature
21+
- Performance improvement
22+
- User experience enhancement
23+
- Documentation improvement
24+
- API/Interface improvement
25+
- Integration with other tools
26+
- Other (specify in description)
27+
validations:
28+
required: true
29+
- type: textarea
30+
id: detailed-description
31+
attributes:
32+
label: Detailed Description
33+
description: |
34+
Provide a detailed description of your idea or suggestion.
35+
Include:
36+
- What problem does this solve?
37+
- How would this benefit users?
38+
- Are there any alternatives you've considered?
39+
placeholder: Describe your idea in detail...
40+
value:
41+
validations:
42+
required: true
43+
- type: textarea
44+
id: use-case
45+
attributes:
46+
label: Use Case / Example
47+
description: |
48+
Provide a concrete use case or example of how this feature would be used.
49+
If applicable, include:
50+
- Example code or configuration
51+
- Workflow description
52+
- Expected input/output
53+
placeholder: |
54+
**Example usage:**
55+
```python
56+
# How users might use this feature
57+
```
58+
59+
**Use case:**
60+
This would help users who...
61+
value:
62+
validations:
63+
required: false
64+
- type: textarea
65+
id: related-work
66+
attributes:
67+
label: Related Work / References
68+
description: |
69+
Are there similar features in other tools, papers, or projects that inspired this idea?
70+
Include links to relevant resources, publications, or implementations.
71+
placeholder: |
72+
- Similar feature in [other tool]: [link]
73+
- Relevant paper: [citation/link]
74+
- Related discussion: [link]
75+
value:
76+
validations:
77+
required: false
78+
- type: textarea
79+
id: implementation-thoughts
80+
attributes:
81+
label: Implementation Thoughts
82+
description: |
83+
If you have ideas about how this might be implemented, share them here.
84+
This could include:
85+
- Potential approaches
86+
- Technical considerations
87+
- Whether you'd be interested in contributing to the implementation
88+
placeholder: Any thoughts on how this could be implemented...
89+
value:
90+
validations:
91+
required: false
92+
- type: textarea
93+
id: additional-context
94+
attributes:
95+
label: Additional Context
96+
description: Any other information that would be helpful for understanding or evaluating this suggestion.
97+
placeholder: Additional details, context, or considerations...
98+
value:
99+
validations:
100+
required: false

‎.github/DISCUSSION_TEMPLATE/potential-bug.yml‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
name: Potential Bug Discussion
2+
description: Discuss behavior that might be a bug before creating a formal issue - include reproducible examples
3+
labels: ["potential bug", "question"]
4+
body:
5+
- type: textarea
6+
id: summary
7+
attributes:
8+
label: What seems to be wrong?
9+
description: |
10+
Describe the behavior you think might be a bug.
11+
Use this template when you're not sure if something is a bug or if you need help confirming the issue before creating a formal bug report.
12+
placeholder: Describe what you think might be wrong...
13+
value:
14+
validations:
15+
required: true
16+
- type: input
17+
id: version
18+
attributes:
19+
label: DeePMD-kit Version
20+
description: "Run `dp --version` to check."
21+
placeholder: "e.g., 2.2.7"
22+
validations:
23+
required: true
24+
- type: input
25+
id: backend-version
26+
attributes:
27+
label: Backend and Version
28+
description: "Which backend version? (shown when running DeePMD-kit)"
29+
placeholder: "e.g., TensorFlow v2.15.0"
30+
validations:
31+
required: true
32+
- type: dropdown
33+
id: installation-method
34+
attributes:
35+
label: How did you install DeePMD-kit?
36+
options:
37+
- conda
38+
- pip
39+
- docker
40+
- Built from source
41+
- Offline packages
42+
- Others (specify below)
43+
validations:
44+
required: true
45+
- type: textarea
46+
id: expected-behavior
47+
attributes:
48+
label: What did you expect to happen?
49+
description: Describe what you think should happen.
50+
placeholder: I expected...
51+
value:
52+
validations:
53+
required: true
54+
- type: textarea
55+
id: actual-behavior
56+
attributes:
57+
label: What actually happened?
58+
description: Describe what you observed instead.
59+
placeholder: Instead, what happened was...
60+
value:
61+
validations:
62+
required: true
63+
- type: textarea
64+
id: reproducible-example
65+
attributes:
66+
label: Reproducible Example
67+
description: |
68+
**This is crucial for confirming if this is a bug!**
69+
70+
Please provide a complete, minimal example that reproduces the issue:
71+
- Input files (attach small files or paste relevant content)
72+
- Exact commands you ran
73+
- Configuration files
74+
- Complete error messages or unexpected output
75+
- System information if relevant
76+
77+
The goal is to provide enough information that others can reproduce the exact same behavior.
78+
placeholder: |
79+
**Files and setup:**
80+
```
81+
# Directory structure
82+
myproject/
83+
├── input.json
84+
├── data/
85+
│ ├── type_map.raw
86+
│ └── set.000/
87+
│ ├── coord.npy
88+
│ └── energy.npy
89+
```
90+
91+
**Configuration (input.json):**
92+
```json
93+
{
94+
"model": {
95+
// your configuration
96+
}
97+
}
98+
```
99+
100+
**Commands:**
101+
```bash
102+
dp train input.json
103+
```
104+
105+
**Output/Error:**
106+
```
107+
# Complete error message or unexpected output
108+
```
109+
110+
**System info:**
111+
- OS: Ubuntu 20.04
112+
- Python: 3.9.7
113+
- Hardware: [relevant specs]
114+
value:
115+
validations:
116+
required: true
117+
- type: textarea
118+
id: investigation
119+
attributes:
120+
label: What have you tried?
121+
description: |
122+
What steps have you taken to investigate or work around this issue?
123+
- Different configurations you've tested
124+
- Workarounds you've attempted
125+
- Similar issues you've found online
126+
- Other versions you've tested
127+
placeholder: |
128+
I tried:
129+
1. Changing the configuration to...
130+
2. Testing with a different dataset...
131+
3. Searching for similar issues...
132+
value:
133+
validations:
134+
required: false
135+
- type: textarea
136+
id: additional-context
137+
attributes:
138+
label: Additional Context
139+
description: |
140+
Any other information that might be relevant:
141+
- When did this behavior start?
142+
- Does it happen consistently?
143+
- Any relevant environmental factors?
144+
- Links to related discussions or issues?
145+
placeholder: Additional context that might be helpful...
146+
value:
147+
validations:
148+
required: false

0 commit comments

Comments
 (0)