Skip to content

Commit 0b36f76

Browse files
MMathisLabMMathisLab
authored
dev-guide
Signed-off-by: Mackenzie Mathis <[email protected]>
1 parent 85df5af commit 0b36f76

File tree

1 file changed

+258
-0
lines changed

1 file changed

+258
-0
lines changed

‎docs/DEV_GUIDE.md‎

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
# Development Guide
2+
3+
## Table of Contents
4+
- [Code Review Best Practices](#code-review-best-practices)
5+
- [Issue Management](#issue-management)
6+
- [Collaborative Coding Guidelines](#collaborative-coding-guidelines)
7+
- [Code Formatting](#code-formatting)
8+
9+
## Code Review Best Practices
10+
11+
### For Reviewers
12+
13+
1. **Be Constructive and Respectful**
14+
- Focus on the code, not the person 🔐
15+
- Provide clear, actionable feedback 🚧
16+
- Explain the "why" behind your suggestions
17+
- Use a positive and encouraging tone 💜
18+
19+
2. **Review Checklist**
20+
- Code follows [project style guidelines](https://github.com/AdaptiveMotorControlLab/WorkspaceTemplate/blob/mwm/dev-guide/docs/StyleGuide.md)
21+
- No obvious bugs or security issues
22+
- **Tests** are included and pass
23+
- Documentation is updated
24+
- Performance considerations are addressed
25+
- Error handling is appropriate
26+
27+
3. **Timely Reviews**
28+
- Respond to review requests within 24 hours
29+
- If you can't review immediately, communicate your timeline
30+
- Don't let PRs sit idle for extended periods
31+
32+
4. **Focus Areas**
33+
- Functionality: Does it work as intended?
34+
- Maintainability: Is the code clean and well-structured?
35+
- Testability: Is it easy to test?
36+
- Security: Are there any security concerns?
37+
- Performance: Are there any performance implications?
38+
39+
### For Authors
40+
41+
1. **Before Submitting**
42+
- Make a branch and adhere to the naming convention: `yourname/issue`
43+
- Self-review your changes
44+
- Run all tests locally
45+
- Run the `pre-commit` checks & formatting!
46+
- Update documentation!
47+
- Keep changes focused and manageable -- "MVP-R" what is the minimally viable PR -- would you want to review it?
48+
- Follow the project's commit message conventions
49+
50+
2. **PR Description**
51+
- Clear title describing the change
52+
- Detailed description of changes
53+
- Link to related issues
54+
- Screenshots for UI changes
55+
- Testing instructions
56+
57+
## Issue Management
58+
59+
### Creating Issues
60+
61+
1. **Issue Template**
62+
- Use the provided issue templates
63+
- Fill out all required sections
64+
- Be specific and detailed
65+
66+
2. **Issue Types**
67+
- Bug: Describe the current behavior and expected behavior
68+
- Feature: Explain the use case and benefits
69+
- Enhancement: Detail the improvement
70+
- Documentation: Specify what needs to be updated
71+
72+
3. **Issue Content**
73+
- Clear, descriptive title
74+
- Detailed description
75+
- Steps to reproduce (for bugs)
76+
- Expected vs actual behavior
77+
- Environment details
78+
- Screenshots/videos when relevant
79+
80+
### Managing Issues
81+
82+
1. **Labels**
83+
- Use appropriate labels (bug, enhancement, etc.)
84+
- Priority labels when necessary
85+
- Component/area labels
86+
87+
2. **Assignments**
88+
- Assign issues to specific team members
89+
- Set realistic deadlines
90+
- Update status regularly
91+
92+
3. **Communication**
93+
- Keep discussions in the issue thread
94+
- Tag relevant team members
95+
- Update issue status promptly
96+
97+
## Collaborative Coding Guidelines
98+
99+
### Git Workflow
100+
101+
1. **Branching Strategy**
102+
- Use feature branches for new work
103+
- Branch naming convention: `name/issue-number-description`
104+
- Example: `john/123-add-login-feature`
105+
- Example: `sarah/456-fix-navigation-bug`
106+
- Keep branches up to date with main
107+
- Delete branches after merging
108+
109+
2. **Commits**
110+
- Write clear, descriptive commit messages
111+
- Keep commits focused and atomic
112+
- Reference issue numbers in commits
113+
- Follow conventional commits format
114+
115+
3. **Pull Requests**
116+
- Keep PRs small and focused
117+
- Update PR description as changes are made
118+
- Request reviews from appropriate team members
119+
- Address review comments promptly
120+
121+
### Communication
122+
123+
1. **Team Communication**
124+
- Use appropriate channels for different purposes - use basecamp campfire and github issues/PRs
125+
- Be clear and concise
126+
- Document important decisions!!
127+
- Share knowledge and learnings
128+
129+
2. **Code Documentation**
130+
- Document complex logic in the code with comments!
131+
- Keep README up to date
132+
- Add inline comments when necessary
133+
- Document API changes
134+
135+
3. **Knowledge Sharing**
136+
- Share learnings with the team
137+
- Document common patterns
138+
- Create and maintain team documentation
139+
- Regular team sync-ups, organize them!
140+
141+
### Development Environment
142+
143+
1. **Setup**
144+
- Document environment setup
145+
- Use consistent development tools
146+
- Share configuration/docker files
147+
- Maintain development dependencies
148+
149+
2. **Local Development**
150+
- Follow our development guidelines
151+
- Use consistent formatting tools
152+
- Run tests before committing (see `pre-commits`)
153+
- Keep dependencies updated
154+
155+
3. **Code Quality**
156+
- Use our suggeested linters and formatters
157+
- Follow our style guides
158+
159+
160+
## Code Formatting
161+
162+
### General Formatting Rules
163+
164+
We use the Google Style Guide: https://google.github.io/styleguide/
165+
166+
1. **Indentation**
167+
- Use 2 spaces for indentation
168+
- No tabs
169+
- Maximum indentation level: 4 levels
170+
- Align with opening delimiter
171+
172+
2. **Line Length**
173+
- Maximum line length: 100 characters
174+
- Break long lines at logical points
175+
- Indent continuation lines by 4 spaces
176+
- Break after operators, not before
177+
178+
3. **Whitespace**
179+
- No trailing whitespace
180+
- One blank line between functions/classes
181+
- Two blank lines between major sections
182+
- No multiple consecutive blank lines
183+
- Spaces around operators
184+
- No spaces inside parentheses
185+
- Spaces after commas and semicolons
186+
187+
4. **Naming Conventions**
188+
- Variables: `lower_snake_case`
189+
- Functions: `lower_snake_case`
190+
- Classes: `PascalCase`
191+
- onstants: `UPPER_SNAKE_CASE`
192+
- Files: `lower_snake_case.py`
193+
- Private members: `_single_leading_underscore`
194+
- Modules/Packages: `lower_snake_case`
195+
- Interfaces: `PascalCase` (same as classes, no special prefix)
196+
197+
5. **Comments**
198+
- Use clear, concise comments
199+
- Comment complex logic
200+
- Keep comments up to date
201+
- Remove commented-out code
202+
203+
6. **Imports/Exports**
204+
- Group imports in the following order:
205+
1. Third-party imports
206+
2. Project imports
207+
- Sort imports by `isort` within the groups
208+
- Use named exports
209+
- Avoid default exports
210+
- One import per line
211+
212+
7. **Code Organization**
213+
- One class/component per file
214+
- Group related functionality
215+
- Keep files focused and manageable
216+
- Follow the project's file structure
217+
- RECOMENDED: Maximum file length: 1000 lines
218+
- RECOMENDED: Maximum function length: 50 lines
219+
220+
221+
### Automated Formatting
222+
223+
1. **Pre-commit Hooks**
224+
- Run formatters before commit
225+
- Run linters before commit
226+
- Check for common issues
227+
- Ensure consistent formatting
228+
- Block commits with formatting errors
229+
230+
2. **CI/CD Integration**
231+
- Run formatting checks in pipeline
232+
- Fail builds on formatting errors
233+
- Generate formatting reports
234+
- Enforce style guide compliance
235+
- Use Google's style guide linters
236+
237+
### Google Style Guide Compliance
238+
239+
1. **General Principles**
240+
- Be consistent with existing code
241+
- Be consistent with Google's style guide
242+
- Use Google's official linters
243+
- Follow language-specific style guides
244+
- Document any style guide exceptions
245+
246+
2. **Code Review Requirements**
247+
- Check style guide compliance
248+
- Verify formatting is correct
249+
- Ensure consistent naming
250+
- Validate documentation
251+
- Review for best practices
252+
253+
3. **Style Guide Resources**
254+
- [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
255+
256+
---
257+
258+
Remember: These guidelines are living documents. Feel free to suggest improvements and updates as the team evolves and learns.

0 commit comments

Comments
 (0)