|
| 1 | +# Contributing Guidelines |
| 2 | + |
| 3 | +### Contents |
| 4 | + |
| 5 | +- [Asking Questions](#asking-questions) |
| 6 | +- [Opening an Issue](#opening-an-issue) |
| 7 | +- [Feature Requests](#feature-requests) |
| 8 | +- [Submitting Pull Requests](#submitting-pull-requests) |
| 9 | +- [Coding Style](#coding-style) |
| 10 | + |
| 11 | +## Asking Questions |
| 12 | + |
| 13 | +Questions should be asked in the [discussion](https://docs.github.com/en/discussions/quickstart) section of this repository. |
| 14 | +Please keep in mind that we don't provide formal support, and will not help with solving research questions. Questions |
| 15 | +should only focus on the usage of `aflow` itself. |
| 16 | + |
| 17 | +## Opening an Issue |
| 18 | +Before [creating an issue](https://help.github.com/en/github/managing-your-work-on-github/creating-an-issue), check if |
| 19 | +you are using the latest version of `aflow`. If you are not up-to-date, see if updating fixes your issue first. |
| 20 | + |
| 21 | +### Reporting Security Issues |
| 22 | +If you discover a security issue, please bring it to our attention right away! **DO NOT** file a public issue for |
| 23 | +security vulnerabilities. Instead, email us at **aflow_sec@materials.duke.edu**. |
| 24 | + |
| 25 | +### Bug Reports and Other Issues |
| 26 | +A great way to contribute to `aflow` is to send us a detailed issue when you encounter a problem. We always appreciate |
| 27 | +a well-written, thorough bug report. |
| 28 | + |
| 29 | +- **Review the [documentation]()** before opening a new issue. |
| 30 | +- **Do not open a duplicate issue!** Search through existing issues to see if your issue has previously been reported. |
| 31 | + If your issue exists, comment with any additional information you have. You may simply note "I have this problem too", |
| 32 | + which helps prioritize the most common problems and requests. |
| 33 | +- **Prefer using [reactions](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/)**, |
| 34 | + not comments, if you simply want to "+1" an existing issue. |
| 35 | +- **Be clear, concise, and descriptive.** Provide as much information as you can, including steps to reproduce, stack traces, |
| 36 | + compiler errors, library versions, OS versions, and screenshots (if applicable). |
| 37 | +- **Use [GitHub-flavored Markdown](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax).** |
| 38 | + Especially put code blocks and console outputs in backticks (```). This improves readability. |
| 39 | + |
| 40 | +## Feature Requests |
| 41 | +Feature requests are welcome! While we will consider all requests, we cannot guarantee your request will be accepted. |
| 42 | +We want to avoid [feature creep](https://en.wikipedia.org/wiki/Feature_creep). Your idea may be great, but also out-of-scope |
| 43 | +for `aflow`. If accepted, we cannot make any commitments regarding the timeline for implementation and release. However, |
| 44 | +you are welcome to submit a pull request to help! |
| 45 | + |
| 46 | +- **Do not open a duplicate feature request.** Search for existing feature requests first. If you find your feature |
| 47 | + (or one very similar) previously requested, comment on that issue. |
| 48 | +- Be precise about the proposed outcome of the feature and how it relates to existing features. Include implementation |
| 49 | + details if possible. |
| 50 | + |
| 51 | +## Submitting Pull Requests |
| 52 | +While `aflow` is open-source it is not open-contribution. So all code changes will go through the maintainers hands before |
| 53 | +being included in a new public release of `aflow`. Nevertheless, we **love** to receive pull requests! If we include |
| 54 | +parts of a pull request we will add you as a contributor in the combined release commits, and your contribution will be |
| 55 | +marked in at the relevant code sections. |
| 56 | + |
| 57 | +Before [forking the repo](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) |
| 58 | +and [creating a pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests) |
| 59 | +for non-trivial changes, it is usually best to first open an issue to discuss the changes, or discuss your intended |
| 60 | +approach for solving the problem in the comments for an existing issue. |
| 61 | + |
| 62 | +*Note: All contributions will be licensed under [GPLv3](https://choosealicense.com/licenses/gpl-3.0/).* |
| 63 | + |
| 64 | +- **Smaller is better.** Submit **one** pull request per bug fix or feature. A pull request should contain isolated |
| 65 | + changes pertaining to a single bug fix or feature implementation. **Do not** refactor or reformat code that is |
| 66 | + unrelated to your change. It is better to **submit many small pull requests** rather than a single large one. |
| 67 | + Enormous pull requests will take enormous amounts of time to review, or may be rejected altogether. |
| 68 | +- **Coordinate bigger changes.** For large and non-trivial changes, open an issue to discuss a strategy with the |
| 69 | + maintainers. Otherwise, you risk doing a lot of work for nothing! |
| 70 | +- **Prioritize understanding over cleverness.** Write code clearly and concisely. Remember that source code |
| 71 | + usually gets written once and read often. Ensure the code is clear to the reader. The purpose and logic should be |
| 72 | + obvious to a reasonably skilled developer, otherwise you should add a comment that explains it. |
| 73 | +- **Follow existing coding style and conventions.** Keep your code consistent with the style, formatting, and |
| 74 | + conventions in the rest of the code base. When possible, these will be enforced with a linter. Consistency makes |
| 75 | + it easier to review and modify in the future. |
| 76 | +- **Include test coverage.** Add unit tests when possible. Follow existing patterns for implementing tests. |
| 77 | +- **Update the example project** if one exists to exercise any new functionality you have added. |
| 78 | +- **Add documentation.** Document your changes with code doxy comments as described in [docs/README.md](/docs/README.md). |
| 79 | +- **Use the repo's default branch.** Branch from and [submit your pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork) |
| 80 | + to the repo's release branch. |
| 81 | +- **[Resolve any merge conflicts](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github)** that occur. |
| 82 | +- When writing comments, use properly constructed sentences, including punctuation. |
| 83 | +- Use spaces, not tabs. |
| 84 | + |
| 85 | +## Coding Style |
| 86 | + |
| 87 | +C++ code is formatted according to the `.clang-tidy` at the root of the repository. Your IDE will typically detect this file |
| 88 | +and apply formatting as you code, but you should also make sure you apply the formatting as you work. Your IDE will likely have |
| 89 | +a keybind for formatting code, but you can also apply formatting with the `clang-format` program. |
| 90 | + |
| 91 | +You should also use clang-tidy to check for warnings. You may tell your IDE to use the `.clang-format` or `.clang-tidy-fix` files |
| 92 | +at the root of the repository. The latter has less checks, but these are the ones we are stricter about. The checks in the `.clang-tidy-fix` |
| 93 | +should all pass before something can be merged. |
| 94 | + |
| 95 | +Hint: Use `git diff --name-only` or `git diff --name-only --staged` to get a list of changed files to pass to run-clang-tidy and clang-format. |
| 96 | + |
| 97 | +For reference, `clang-tidy -p build --config-file .clang-tidy-fix $(git diff --name-only HEAD $(git merge-base HEAD staging))` will effectively |
| 98 | +be run before a merge can be completed. |
0 commit comments