diff --git a/docs/how-to-guides/software-management/guidelines-for-pull-requests.md b/docs/how-to-guides/software-management/guidelines-for-pull-requests.md new file mode 100644 index 0000000000000000000000000000000000000000..669388e037ec9c89d3ce882056fe5990c97e0935 --- /dev/null +++ b/docs/how-to-guides/software-management/guidelines-for-pull-requests.md @@ -0,0 +1,35 @@ +# Guidelines for Pull Requests + +This page provides guidelines for creating a successful pull request. These guidelines are intended to promote a style of pull request that benefits both the creator of the pull request and the reviewer. + +## Before Writing Code + +- Pull from upstream/main to ensure that your code is up to date +- Ensure that your pull request is directly related to an issue in the repository. If a related issue does not exist, then [create one](./guidelines-for-reporting-issues.md) +- Gauge the complexity of the issue before beginning work. While there is no "magic number" with respect to the number of lines a PR should contain, if it requires more than 250 changed lines of code, then it may be necessary to decompose the issue into a series of smaller issues. + + +## While Addressing the Issue + +- Ensure that your commit messages are meaningful + - Instead of "Fixed bug" or "Addressed PR Feedback," the message should contain information that describes the change. +- Follow the established coding style if one exists for the repository +- Ensure that your changes are accompanied by an entry in the changelog +- Write tests to cover any functionality that is added or changed + + +## When Creating the Pull Request + +After writing code or making relevant changes, create a pull request on the appropriate repository. + +- Completely fill out the pull request template +- Reference the issue with a "fixes," "closes," "resolves," etc. keyword, e.g. "Fixes #489" +- Create comments to clarify any code changes or design decisions that may not be clear to the reviewer + +## Quick PR Guidelines + +Use the following checklist to ensure that your PR follows best practices that will allow for a quick and easy review + +- [ ] The PR is responsible for a single change that is summarized in the changelog. +- [ ] The PR should not change more than 250 lines of code. While this is not always possible, minimizing the size of the PR will ensure that a timely review can take place. +- [ ] The PR must be tested locally before being marked ready for review \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index ca929d145bb6390cc55960335bf89480146c8320..b5a0a3337f2c9b7220dc85791fc394afa09c3565 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -58,6 +58,7 @@ nav: - ISIS Public Release Process: how-to-guides/software-management/public-release-process.md - Software Support: how-to-guides/software-management/software-support.md - Guidelines for Reporting Issues: how-to-guides/software-management/guidelines-for-reporting-issues.md + - Guidelines for Pull Requests: how-to-guides/software-management/guidelines-for-pull-requests.md - ISIS Developer Guides: - How To Write ISIS Tests with CTest and GTest: how-to-guides/isis-developer-guides/writing-isis-tests-with-ctest-and-gtest.md - App Testing CookBook: how-to-guides/isis-developer-guides/app-testing-cookbook.md