From 1dfe872caa8342f428ab3fa2694485ce57988f62 Mon Sep 17 00:00:00 2001
From: Ken Matsui <26405363+ken-matsui@users.noreply.github.com>
Date: Sat, 16 Nov 2024 04:03:57 -0500
Subject: [PATCH] CONTRIBUTING: create (#1039)

---
 CONTRIBUTING.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  30 --------------
 2 files changed, 103 insertions(+), 30 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..f41bcb6c1
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,103 @@
+# Contributing
+
+Please note we have a [code of conduct](https://github.com/poac-dev/.github/blob/main/CODE_OF_CONDUCT.md),
+please follow it in all your interactions with the project.
+
+You can ignore sections marked as "Under Construction".
+
+## How to Contribute
+
+You can contribute to this repository in one of the following ways:
+
+1. **For Trivial Changes**<br>
+   If you believe your change is minor (e.g., typo fixes, small improvements),
+   feel free to make the change directly and submit a pull request (PR).
+2. **For Uncertain Changes**<br>
+   If you're unsure whether your proposed change aligns with the project's
+   goals, we encourage you to discuss it first by opening an issue or starting
+   a discussion.  This helps ensure alignment and reduces potential rework.
+3. **For Exploratory Contributions**<br>
+   If you're unsure but find it easier to share code, you can create a draft PR
+   with the prefix `RFC:` in the title (e.g., `RFC: build: add new feature X`).
+   This signals that the PR is a "Request for Comments" and invites feedback
+   from the maintainers and community.
+
+## Coding Style
+
+Consistency is key to maintaining a clean and readable codebase. As stated in the
+[LLVM Coding Standards](https://llvm.org/docs/CodingStandards.html#introduction):
+
+> **If you are extending, enhancing, or bug fixing already implemented code,
+> use the style that is already being used so that the source is uniform and
+> easy to follow.**
+
+Please follow this principle to ensure the code remains cohesive and easy to
+navigate.
+
+(*Under Construction) Additionally, be mindful of when to use structs vs. classes.  For guidance,
+refer to the [Google C++ Style Guide: Structs vs. Classes](https://google.github.io/styleguide/cppguide.html#Structs_vs._Classes).
+
+### Formatting and Linting
+
+Before submitting a PR, ensure your code adheres to the project's coding
+standards by running the following tools:
+
+1. Run the linter (`cpplint`)
+   ```bash
+   poac lint --exclude srcOld --exclude testsOld
+   ```
+2. Run the formatter (`clang-format`)
+   ```bash
+   poac fmt --exclude srcOld --exclude testsOld
+   ```
+3. Run the static analyzer (`clang-tidy`)
+   ```bash
+   poac tidy  # or make tidy
+   ```
+
+### Testing
+
+Always validate your changes to ensure they do not introduce regressions or
+break existing functionality:
+
+```bash
+poac test  # or make test
+```
+
+### Naming Conventions (*Under Construction)
+
+The project's naming conventions are specified in the
+[.clang-tidy](.clang-tidy) file.  Here's a brief summary:
+
+- **Files/Directories**: `PascalCase`
+- **Types/Classes**: `PascalCase`
+- **Variables**: `snake_case`
+- **Member Variables**: `snake_case_`
+- **Functions**: `camelCase`
+- **Methods**: `camelCase_`
+
+## Commit Message
+
+We generally follow the
+[Git Contribution Guidelines](https://git-scm.com/docs/SubmittingPatches#describe-changes).
+
+- **First Line**: Ensure the first line of your commit message adheres to the
+  guidelines for a concise and clear summary.
+- **Body**: While not mandatory, it is recommended to follow the rest of the
+  guidelines to maintain consistency and provide helpful context for future
+  readers.
+
+## Pull Request Style
+
+When creating a PR:
+
+1. **CI**: Verify that all CI checks pass on your fork before submitting the
+   PR.  Avoid relying on the CI of this repository to catch errors, as this
+   can cause delays or stalls for other contributors.
+2. **Commit Structure**: There is no need to squash commits within the PR
+   unless explicitly requested.  Keeping separate commits can help reviewers
+   understand the progression of changes.
+3. **Title and Description**: Ensure the PR title and description are clear,
+   concise, and accurately summarize the changes.  These will serve as the
+   commit message when the PR is merged, so take care to make them informative
+   and professional.
diff --git a/README.md b/README.md
index c0e9d8d10..5eea14c5d 100644
--- a/README.md
+++ b/README.md
@@ -354,36 +354,6 @@ Despite C++ often being overlooked for product development, I believe that Poac
 
 We use [GitHub Discussions](https://github.com/orgs/poac-dev/discussions).
 
-## Contributing
-
-### Before submitting your PR
-
-Please make sure to follow these steps:
-
-#### Run linter (`cpplint`)
-
-```bash
-poac lint --exclude srcOld --exclude testsOld
-```
-
-#### Run formatter (`clang-format`)
-
-```bash
-poac fmt
-```
-
-#### Run tests
-
-```bash
-poac test  # or make test
-```
-
-#### Run `clang-tidy`
-
-```bash
-poac tidy  # or make tidy
-```
-
 ## Acknowledgements
 
 This project exists thanks to all the people who contribute.