You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Your commits explain the `what` and `where` you made changes in the code. Your commit messages explain `why` you made the commits. You do not need to reiterate this. This PR is meant to address the big picture, `Why`
2
-
1
+
Your commits explain the `who`, `what`, `where` and `when` of these changes. Your code shows the `how`. You do not need to reiterate this. This PR should complete the picture by explaining `why` these changes are necessary.
2
+
Please complete the fields below, replacing or removing placeholder text where necessary:
3
+
3
4
### Justification
4
5
5
-
Describe the big picture of your changes here to communicate to the reviewers why they should accept this pull request.
6
-
Please describe the importance/impact of the problem and a description of how the changes in this pull request will address, resolve or improve the problem.
7
-
If it fixes a bug or resolves a feature request, be sure to link to the issue below
6
+
Please describe the importance/impact of the problem and a description of how the changes in this pull request will address, resolve or improve it. This section should sufficiently explain to reviewers why these changes should be approved.
7
+
If the proposed changes should close an issue, be sure to link to it below:
8
+
Fixes #?
8
9
9
10
### Types of changes
10
11
11
-
What types of changes does your code introduce? Put an `x` in the boxes that apply
12
+
What types of changes does this pull request introduce? Put an `x` in the boxes that apply.
13
+
This will inform the new release number.
12
14
13
-
-[ ]Bugfix (non-breaking change which fixes an issue)
14
-
-[ ]New feature (non-breaking change which adds functionality)
15
+
-[ ]Fix (non-breaking change which fixes a bug)
16
+
-[ ]Feature (non-breaking change which adds or changes functionality)
15
17
-[ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
16
-
-[ ]Documentation Update (if none of the other choices apply)
18
+
-[ ]Other change (if none of the other choices apply)
17
19
18
20
### Checklist/Reminders
19
21
@@ -26,18 +28,18 @@ Put an `x` in the boxes that apply
26
28
27
29
### Further comments
28
30
29
-
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc...
31
+
If this is a relatively large or complex change, kick off a discussion by explaining why you chose the solution you did, what alternatives you considered, problems you may have encountered, etc.
30
32
31
-
### Reviewer instructions:
33
+
### Reviewer instructions
32
34
33
35
Assign at least 2 reviewers:
34
-
* one of which should be a maintainer,
35
-
* the others should be familiar with the subject changes.
36
+
* one of which should be a maintainer of this repo,
37
+
* the others should be familiar with the subject or problem.
36
38
37
39
Please detail the process reviewers will need to follow to properly test these changes. It is especially helpful to identify the exact code needed to conduct a local build/review/test and to specify any aspects of the testing that may not be obvious.
38
40
39
-
40
41
### Formatting
41
42
42
43
This repo contains an `air.toml` file that automatically formats code to a set of standards.
43
-
It is preferred that contributors and reviewers install the [air](https://posit-dev.github.io/air/) formatting tool.
44
+
It is preferred that contributors and reviewers install the [Air](https://posit-dev.github.io/air/) formatting tool.
45
+
Code submitted in this pull request will be automatically checked for correct formatting.
-[Certificate of Origin](#crab-certificate-of-origin)
16
18
-[Credits](#pray-credits)
17
19
18
20
> **This guide serves to set clear expectations for everyone involved with the project so that we can improve it together while also creating a welcoming space for everyone to participate. Following these guidelines will help ensure a positive experience for contributors and maintainers.**
@@ -25,14 +27,36 @@ Please review our [Code of Conduct](CODE_OF_CONDUCT.md). It is in effect at all
25
27
26
28
GitHub issues are not the appropriate place to debug your specific project, but should be reserved for filing bugs and feature requests.
27
29
30
+
## :whale: Acceptable Types
31
+
32
+
Throughout this project, we use standard `types` to communicate more effectively. These types are used when labeling issues, creating branches, committing changes and naming pull requests. Please reference and use the `types` below when contributing to this project:
33
+
34
+
-**fix:** Patch an unexpected or undesirable behavior
35
+
36
+
-**build:** Add or modify build-related components (e.g. workflows, versioning, etc.)
37
+
38
+
-**chore:** Maintenance of product or repository (e.g. gitignore, templates, etc.)
39
+
40
+
-**docs:** Add or modify documentation
41
+
42
+
-**feature:** Add or modify a feature or functionality
43
+
44
+
-**refactor:** Rewrite or restructure code without altering behavior
45
+
46
+
-**style:** Reformat code style without altering behavior
47
+
48
+
-**test:** Add or modify tests
49
+
50
+
All issues, branches, commits and pull requests should align with one of the above `types`. If you have questions or need assistance, please reach out to a maintainer.
51
+
28
52
## :fishing_pole_and_fish: Opening an Issue
29
53
30
-
Before [creating an issue](https://help.github.com/en/github/managing-your-work-on-github/creating-an-issue), check if you are using the latest version of the project. If you are not up-to-date, see if updating fixes your issue first.
54
+
Before [creating an issue](https://help.github.com/en/github/managing-your-work-on-github/creating-an-issue), check that you are using the latest version of the project. If you are not up-to-date, see if updating fixes your issue first.
31
55
32
56
### :blowfish: Bug Reports and Other Issues
33
57
34
-
A great way to contribute to the project is to send a detailed issue when you encounter a problem. We ask you to please create a [reprex](https://reprex.tidyverse.org/).
35
-
We always appreciate a well-written, thorough bug report. This helps us quickly identify and fix the problem.
58
+
A great way to contribute to the project is to send a detailed issue when you encounter a problem.
59
+
This repo has a 'Bug Report' issue template that will guide you in submitting a well-written, thorough bug report. If possible, please also create a [reprex](https://reprex.tidyverse.org/) and include it in your issue. This helps us quickly identify and fix the problem.
36
60
37
61
When opening an issue, please follow these guidelines:
38
62
@@ -46,22 +70,38 @@ When opening an issue, please follow these guidelines:
46
70
47
71
-**Use [GitHub-flavored Markdown](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax).** Especially put code blocks and console outputs in backticks (```). This improves readability. In short, since you are most likely a developer, **provide a ticket that you would like to receive**.
48
72
49
-
-**Review the documentation** before opening a new issue.
50
-
51
-
-**Do not open a duplicate issue!** Search through existing issues to see if your issue has previously been reported. If your issue exists, comment with any additional information you have. You may simply note "I have this problem too", which helps prioritize the most common problems and requests.
73
+
-**Do not open a duplicate issue!** Search through existing issues to see if your issue has previously been reported. If your issue exists, comment with any additional information you have. You may simply leave a reaction to bump the issue, which helps prioritize the most common problems and requests.
52
74
53
75
-**Fully complete the provided issue template.** The bug report template requests all the information we need to quickly and efficiently address your issue. Be clear, concise, and descriptive. Provide as much information as you can, including steps to reproduce, stack traces, compiler errors, library versions, OS versions, and screenshots (if applicable).
54
76
55
-
## :tropical_fish: Feature Requests
77
+
### :tropical_fish: Feature Requests
78
+
79
+
Feature requests are more than welcome! While we will consider all requests, we cannot guarantee your request will be accepted or provide the timeline for implementation and release.
56
80
57
-
Feature requests are more than welcome! While we will consider all requests, we cannot guarantee your request will be accepted or the timeline for implementation and release.
81
+
-**Do not open a duplicate feature request.** Search for existing feature requests first. If you find your feature (or one very similar) previously requested, comment on or add a reaction to that issue.
58
82
59
-
-**Do not open a duplicate feature request.**Search for existing feature requests first. If you find your feature (or one very similar) previously requested, comment on that issue.
83
+
-**Fully complete the provided issue template.**The 'Feature Request' template asks for all necessary information for us to begin a productive conversation.
60
84
61
-
-**Fully complete the provided issue template.**The feature request template asks for all necessary information for us to begin a productive conversation.
85
+
-**Be precise**about the proposed outcome of the feature and how it relates to existing features. Include all implementation details.
62
86
63
-
- Be precise about the proposed outcome of the feature and how it relates to existing features. Include all implementation details.
87
+
## :anchor: Creating a Branch
64
88
89
+
Many contributions to this project will make use of [branching](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches). This repo has two permanent branches: `main` and `dev`. To contribute via branching, you should create a branch from and pull request to the `dev` branch. Your branch name should follow these conventions:
90
+
91
+
- Use `type/i#-describe-branch-purpose`, where # is the number of the target issue
92
+
- Prefix with the `type` of change the branch will introduce (see [acceptable `types`](#whale-acceptable-types) above)
93
+
- Include an issue number in your branch name (your changes should relate to an [existing issue](#fishing_pole_and_fish-opening-an-issue))
94
+
- Provide a clear but concise description of the branch's purpose
95
+
96
+
## :memo: Writing Commit Messages
97
+
98
+
Please write a **conventional** commit message:
99
+
100
+
1. Use `type(optional scope): commit message` structure (see above for [acceptable `types`](#whale-acceptable-types))
101
+
1. Separate changes into their own commits with unique messages
102
+
1. Write using imperative mood (example: "fix: correct the food web")
103
+
1. Include a `scope` if a commit serves a larger purpose (example: "refactor(food web fix): reorder data ingestion")
104
+
1. Be as brief as possible without losing clarity
65
105
66
106
## :fish_cake: Submitting Pull Requests
67
107
@@ -71,7 +111,11 @@ We appreciate pull requests! Before [forking the repo](https://help.github.com/e
71
111
72
112
**Guidelines for happy pull requests:**
73
113
74
-
-**Communication is the key to success.** If you are unsure about something, ask! We are happy to help. We have an open channel of communication, make sure to reach us up and further develop your ideas or changes before working on a pull request.
114
+
-**Title meaningfully.** Consistent with the convention elsewhere, please title your pull request: "Type(#i): Describe Change Purpose", where "i" is the number of the issue addressed by the PR. Please reference the [acceptable types](#whale-acceptable-types) above.
115
+
116
+
-**Request appropriate reviewers.** At the very least, please request review from one or all of the project maintainers (maintainers are listed on the [README](README.md)). You should include additional reviews from people familiar with the subject or problem your proposed changes address.
117
+
118
+
-**Communication is the key to success.** If you are unsure about something, ask! We are happy to help. We have an open channel of communication, make sure to reach out and further develop your ideas or changes before working on a pull request.
75
119
76
120
-**Smaller is better.** Submit **one** pull request per bug fix or feature. A pull request should contain isolated changes pertaining to a single bug fix or feature implementation. **Do not** refactor or reformat code that is unrelated to your change. It is better to **submit many small pull requests** rather than a single large one. Enormous pull requests will take enormous amounts of time to review, or may be rejected altogether.
77
121
@@ -85,39 +129,15 @@ We appreciate pull requests! Before [forking the repo](https://help.github.com/e
85
129
86
130
-**Update the example project** if one exists to exercise any new functionality you have added.
87
131
88
-
-**Add documentation.** Document your changes with code doc comments or in existing guides.
89
-
90
-
-**Update the CHANGELOG** for all enhancements and bug fixes. Include the corresponding issue number if one exists, and your GitHub username.
132
+
-**Add documentation.** Document your changes with code comments or other documentation.
91
133
92
-
-**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) to the repo's default branch. In Rpath case it will be `dev`.
134
+
-**Use the correct 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) to the correct branch (see above for [branching instructions](#anchor-creating-a-branch)). In this repo, it will be the `dev` branch.
93
135
94
136
-**[Resolve any merge conflicts](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github)** that occur.
95
137
96
-
- When writing comments, use properly constructed sentences, including punctuation.
97
-
98
-
- Use spaces, not tabs.
99
-
100
-
## :memo: Writing Commit Messages
101
-
102
-
Please [write a great commit message](https://chris.beams.io/posts/git-commit/).
103
-
104
-
1. Separate subject from body with a blank line
105
-
1. Limit the subject line to 50 characters
106
-
1. Capitalize the subject line
107
-
1. Do not end the subject line with a period
108
-
1. Use the imperative mood in the subject line (example: "Fix food web issue")
109
-
1. Wrap the body at about 72 characters
110
-
1. Use the body to explain **why**, *not what and how* (the code shows that!)
111
-
1. If applicable, prefix the title with the relevant component name. (examples: "[Docs] Fix typo", "[Profile] Fix missing avatar")
112
-
1. Link the commit message to the issue it fixes, if applicable. (example: "Fixes #1234")
113
-
114
-
115
138
## :shark: Coding Style
116
139
117
-
Consistency is the most important. Following the existing style, formatting, and naming conventions of the file you are modifying and of the overall project. Failure to do so will result in a prolonged review process that has to focus on updating the superficial aspects of your code, rather than improving its functionality and performance.
118
-
119
-
For example, if all private properties are prefixed with an underscore `_`, then new ones you add should be prefixed in the same way. Or, if methods are named using camelcase, like `thisIsMyNewMethod`, then do not diverge from that by writing `this_is_my_new_method`. You get the idea. If in doubt, please ask or search the codebase for something similar.
120
-
140
+
Consistent formatting is an essential part of effective collaboration and communication. Reading, writing and reviewing code all benefit from following the standards and conventions of a project. Failure to do so will result in a prolonged review process that has to focus on updating the superficial aspects of your code, rather than improving its functionality and performance. This repo uses and adheres to the [tidyverse style guide](https://style.tidyverse.org/) and the [Air autoformatting tool](https://posit-dev.github.io/air/) that follows it. Please read and follow these guides as you make contributions to the project.
0 commit comments