docs: add CONTRIBUTING.md with coding conventions and review guide#84
docs: add CONTRIBUTING.md with coding conventions and review guide#84
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a first-version contributing guide and links it from the main README to standardize coding conventions and review expectations for esp-stub-lib.
Changes:
- Add
CONTRIBUTING.mddocumenting naming, weak/strong overrides, error handling, ROM usage, memory/logging rules, SOC headers, CMake patterns, and review checklist. - Link the new contributing guide from the README “Contributing” section.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| README.md | Adds a pointer to the new contributing guide. |
| CONTRIBUTING.md | Introduces a comprehensive contribution/conventions document and reviewer checklist. |
|
|
||
| - No `malloc`, `free`, `calloc`, `realloc`. | ||
| - Use stack variables for temporaries. | ||
| - Avoid large `static` variables. The library serves both OpenOCD and esptool.They |
There was a problem hiding this comment.
Fix missing space after the period: esptool.They should be esptool. They.
| - Avoid large `static` variables. The library serves both OpenOCD and esptool.They | |
| - Avoid large `static` variables. The library serves both OpenOCD and esptool. They |
| ### Statistics | ||
|
|
||
| Use the `s_` prefix when you need a `static`: |
There was a problem hiding this comment.
This section is describing static variables (statics), not statistics. Renaming the heading and the last sentence (e.g., “### Statics” and “prefer parameters over statics”) would avoid confusion for contributors.
|
|
||
| ## Logging | ||
|
|
||
| Compile time conditional (`STUB_LOG_ENABLED`). Use the macros: |
There was a problem hiding this comment.
Hyphenate the compound modifier: Compile time → Compile-time.
| Compile time conditional (`STUB_LOG_ENABLED`). Use the macros: | |
| Compile-time conditional (`STUB_LOG_ENABLED`). Use the macros: |
👋 Hello erhankur, we appreciate your contribution to this project! Click to see more instructions ...
Review and merge process you can expect ...
|
dobairoland
left a comment
There was a problem hiding this comment.
@erhankur Thank you very much for taking the time and making this. Awesome. I don't have any specific requirement for the rules - I'm happy that they are defined and will help all future contributors.
Please consider linking the document from the copilot config file so it would use it for reviews.
The guide is based on patterns already followed across the codebase. It covers naming, weak/strong overrides,
error handling, ROM functions, memory rules, logging, SOC headers, CMake integration, testing, and code style.
This is the first version. It covers the essentials but is open to discussion and suggestions.