From f54356e4e10ba951c07ad4ee0575503197726506 Mon Sep 17 00:00:00 2001 From: Andrei-Fabian-Pop Date: Tue, 3 Sep 2024 14:03:22 +0300 Subject: [PATCH] docs: Add CONTRIBUTING guidelines Signed-off-by: Andrei-Fabian-Pop --- .github/contributing/coding-guidelines.md | 27 ++++++ .github/contributing/project-structure.md | 107 ++++++++++++++++++++++ CONTRIBUTING.md | 9 ++ README.md | 4 + 4 files changed, 147 insertions(+) create mode 100644 .github/contributing/coding-guidelines.md create mode 100644 .github/contributing/project-structure.md create mode 100644 CONTRIBUTING.md diff --git a/.github/contributing/coding-guidelines.md b/.github/contributing/coding-guidelines.md new file mode 100644 index 0000000000..25d87265a0 --- /dev/null +++ b/.github/contributing/coding-guidelines.md @@ -0,0 +1,27 @@ +# Scopy C++ coding guidelines + +- Member variables should be prefixed with `m_` +- Getters and setters should be like in the following example: +```c++ +bool m_enable; +bool enabled() const { return m_enable; } +void setEnabled(bool en) { m_enable = en; } +``` +- `Variables` are `camelCase` (start with lowercase, and each word after that is uppercase) +- `Class names` always start with an `uppercase` letter. +- File names should be in full lowercase (header and source files) +- The class name should match the file name (case-insensitive) +- Always use explicit Qt macros (e.g. use `Q_SLOTS`, do not use slots) +- When naming classes, refrain from using Manager/Controller too much - https://stackoverflow.com/questions/1866794/naming-classes-how-to-avoid-calling-everything-a-whatevermanager and https://gist.github.com/hurricane-voronin/9ceccace0fd530bbf17c83b059c86eb7 +- When implementing design patterns keep naming consistent so everyone is on the same page + - Strategy pattern example - https://github.com/analogdevicesinc/scopy/tree/dev/plugins/regmap/src/readwrite + - Singleton pattern example - https://github.com/analogdevicesinc/scopy/blob/dev/pluginbase/include/pluginbase/preferences.h + - Factory pattern example - https://github.com/analogdevicesinc/scopy/blob/dev/core/include/core/devicefactory.h + - Are factories singleton? + - Or are they static classes? + - Do they have QObject parents? + - Resources for design patterns: + - https://refactoring.guru/ + - https://www.youtube.com/watch?v=v9ejT8FO-7I&list=PLrhzvIcii6GNjpARdnO4ueTUAVR9eMBpc + - Design Patterns: Elements of Reusable Object-Oriented Software Design patterns – Gang of Four +- Be aware of code smells - https://refactoring.guru/refactoring/smells , while not errors in the common sense, these "signs" suggest a deeper problem in design/architecture. diff --git a/.github/contributing/project-structure.md b/.github/contributing/project-structure.md new file mode 100644 index 0000000000..c3703b4c2f --- /dev/null +++ b/.github/contributing/project-structure.md @@ -0,0 +1,107 @@ +# Git Process + +### Some resources + +- https://opensource.com/article/18/6/anatomy-perfect-pull-request + +#### When working on a new feature: +- Move to the starting point +- Resynchronize tree with remote +- Create new branch from starting branch + +#### Example: + +```bash +git checkout dev +git pull +git checkout -b +``` + +> [!NOTE] +> Prefixing branch name: +> - dev_ for branches starting from dev +> - ci_ for ci work +> - exp_ for experimental work – will never be merged back +> - v - for releases and release candidates +> +> Example: +> ```bash +> git checkout -b dev_cursor_refactor origin/dev +> ``` + +- Implement feature – commit and push work as needed – refer to commit message structure +- Apply code styling - (usually done by running `./tools/format.sh`) +- Resynchronize with latest changes to starting point and push again. Example +```bash +git fetch +git rebase origin/dev +git push +``` +- Create pull request +- Make sure CI tests pass. Assign reviewers. +- Discuss review, and implement changes as needed. Try to refrain from force pushing at this point as it makes everyones job a little harder. When finished, all the commits can be squashed/reorganized as needed +- Make sure PR is synchronized with starting point. Test feature before merge. +- Close PR - use only `Rebase and merge` or `Squash and merge`. Do not use Create merge commit + +# Git commit message structure + +Some resources: +- https://cbea.ms/git-commit/ +- https://github.blog/2022-06-30-write-better-commits-build-better-projects/ +- https://dhwthompson.com/2019/my-favourite-git-commit + +A commit message should have the following structure: + +```text +prefix/subprefix: short description (max 80 char) + +longer description that explains why the change is needed as well as some +subtleties of the change. Can refer to other commit SHA as well as github +issues + +Signed-off by: author.name +``` + +Refer to project specific documentation for module names and description + +Some possible prefixes: + +| Module name | Description | +|-------------|-----------------------------------------------------------------------------------------------------------| +| project | A change in project structure – nonfunctional changes | +| tree | Change that applies to many files in the project – such as styling, addressing a warning, etc | +| cmake | Changes related to general project cmake or cmake modules. (assuming cmake is the project config tool) | +| ci | CI and deployment | +| doc | Add documentation or documentation infrastructure | +| tests | Add tests or testing infrastructure | +| toolsTools | related to the project | +| general | A change that affects multiple parts of Scopy – should not be used unless other module names do not apply | +| \ | Project specific module | + + +# Default Branches + +| Branch name | Description | +|--------------------|--------------------------------------------------------------------------------------------------------------------| +| dev | Contains next major features of the project – contains multiple features bundled together. Will be merged to main. | +| main | main branch – used to integrate changes and create releases. Locked – history cannot be overwritten | +| maint-1.5 | maintenance branch for the projectv1.5 – bug fixes for scopy 1.5 are created here. Used to create v1.5.x releases | +| v[-rc] | Version branch of the project. Versioned releases and release candidates. Locked. | + +# Review process +After creating a pull request, the developer should ask reviewers to review their code. Ideally the pull request +should contain only one feature/bug which can be easily understood by the reviewer. + +When reviewing keep a few things in mind + +- Does the pull request pass automated tests/ styling checks/ etc. ? +- Is the intent clear ? +- Is the solution directly addressing the problem ? +- Is the solution clear ? +- Is the code implementing the solution clear ? Can it be simplified ? +- Does the code introduce any maintenance effort ? +- Are there any side effects to the solution ? +- Can the solution be tested ? +- Can the solution be automatically tested ? Is the automatic test implemented ? +- Are code commits structured nicely ? Commits shouldn't be too big, each commit should address a single change in the code. There should be no " + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..6c2ca8b6b5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,9 @@ +# Contributing to Scopy + +Thank you for considering contributing to the Scopy project! Contributions from the community are what make this project thrive. Whether you're fixing bugs, improving documentation, or developing new features, your efforts help us build a better tool for everyone. + +This guide outlines the processes and standards that we follow to ensure consistency, quality, and maintainability across the project. Adhering to these guidelines will make it easier for the Scopy contributions to review and integrate the changes into the project. + +## [Coding Guidelines](.github/contributing/coding-guidelines.md) + +## [Project Structure](.github/contributing/project-structure.md) diff --git a/README.md b/README.md index 8d5901f500..c69180d68e 100644 --- a/README.md +++ b/README.md @@ -17,3 +17,7 @@ Nightly builds are available under the [Continuous build](https://github.com/ana - Android (aarch64) Complete instalation and usage instructions can be found on our [Wiki](https://wiki.analog.com/university/tools/m2k/scopy) page. + +## Contributing + +See the [CONTRIBUTING file](CONTRIBUTING.md) for guidance on contributing to this project.