Skip to content

Commit a9ea73b

Browse files
DucksssDucksss
authored
Flesh out contributor guide (#6961)
1 parent afd1ac4 commit a9ea73b

4 files changed

Lines changed: 232 additions & 55 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 225 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,225 @@
1-
[Please press here if you want to contribute!](./doc/CONTRIBUTING.md)
1+
# Contributing to CASA
2+
3+
Thank you for helping CASA and Ruby for Good. CASA is a Ruby on Rails
4+
application that helps Court Appointed Special Advocate organizations support
5+
volunteers, supervisors, and administrators.
6+
7+
By participating in this project, you agree to follow the Ruby for Good
8+
[code of conduct](https://github.com/rubyforgood/code-of-conduct).
9+
10+
## Where to ask questions
11+
12+
Use the channel that keeps your question closest to the work:
13+
14+
- Ask issue-specific questions in the GitHub issue.
15+
- Ask pull request questions in the pull request thread.
16+
- Join the Ruby for Good [Slack](https://join.slack.com/t/rubyforgood/shared_invite/zt-35218k86r-vlIiWqig54c9t~_LkGpQ7Q)
17+
and use the `#casa` channel for fast help.
18+
- Join the CASA [Discord](https://discord.gg/qJcw2RZH8Q) for office hours and
19+
project discussion.
20+
- Check the CASA [Google Calendar](https://bit.ly/casacal) for office hours and
21+
stakeholder meetings.
22+
23+
Maintainers usually check issues and pull requests every day or three. If you
24+
have been blocked for a few days, leave a concise GitHub comment or ask in
25+
`#casa`.
26+
27+
## Getting set up
28+
29+
The [README](README.md) is the main setup guide. Start there for the current
30+
Ruby, Node.js, PostgreSQL, seed user, and local server instructions.
31+
32+
Fast setup options:
33+
34+
- Use [GitHub Codespaces](https://codespaces.new/rubyforgood/casa/tree/main?quickstart=1)
35+
if you want a browser-based environment.
36+
- Follow the README [local setup instructions](README.md#local-setup-instructions)
37+
if you want to run CASA on your machine.
38+
- Use the [Docker setup guide](doc/DOCKER.md) if you prefer containers.
39+
40+
Platform-specific notes:
41+
42+
- [Linux setup](doc/LINUX_SETUP.md)
43+
- [macOS setup](doc/MAC_SETUP.md)
44+
- [Nix setup](doc/NIX_SETUP.md)
45+
- [Windows Subsystem for Linux setup](doc/WSL_SETUP.md)
46+
47+
After setup, verify the app with:
48+
49+
```sh
50+
bin/setup
51+
bin/dev
52+
```
53+
54+
Then open <http://localhost:3000/> and log in with one of the README
55+
[seed users](README.md#logging-in-with-seed-users).
56+
57+
When you pull fresh changes from `main`, run:
58+
59+
```sh
60+
bin/update
61+
```
62+
63+
## Finding something to work on
64+
65+
Good starting places:
66+
67+
- [Good First Issue](https://github.com/rubyforgood/casa/labels/Good%20First%20Issue)
68+
issues are intended for new contributors.
69+
- [Help Wanted](https://github.com/rubyforgood/casa/labels/Help%20Wanted)
70+
issues are open to community contributors.
71+
- [Unassigned open issues](https://github.com/rubyforgood/casa/issues?q=is%3Aissue%20is%3Aopen%20no%3Aassignee)
72+
are available if no recent comment says someone is already working on them.
73+
74+
Before starting:
75+
76+
1. Read the issue and recent comments.
77+
2. Make sure the issue is not assigned.
78+
3. Comment that you would like to work on it and ask to be assigned.
79+
4. Wait for a maintainer if the issue needs clarification.
80+
81+
Only take multiple issues when they are closely related and can be solved in the
82+
same pull request. If you want to work on something that does not have an issue,
83+
open an issue first so maintainers can confirm the direction.
84+
85+
If you cannot continue an assigned issue, comment on the issue so someone else
86+
can pick it up. The repository warns contributors after 10 days of inactivity and
87+
may unassign inactive issues after 15 days.
88+
89+
## Development workflow
90+
91+
Fork the repository unless a maintainer has given you direct commit access.
92+
93+
Add the upstream remote once:
94+
95+
```sh
96+
git remote add upstream https://github.com/rubyforgood/casa.git
97+
```
98+
99+
Start each issue from an updated `main` branch:
100+
101+
```sh
102+
git checkout main
103+
git pull upstream main
104+
git checkout -b 6910-contributing-guide
105+
```
106+
107+
Use a short, descriptive branch name. Including the issue number helps reviewers,
108+
for example `6910-contributing-guide` or `5979-learning-hours-report`.
109+
110+
Keep the change focused on the issue. Small pull requests are easier to review
111+
and merge than broad rewrites.
112+
113+
## Tests and linters
114+
115+
Run the smallest useful test command while developing, then run the broader
116+
checks before opening a ready pull request.
117+
118+
Common test commands:
119+
120+
```sh
121+
bundle exec rspec
122+
npm run test
123+
```
124+
125+
Targeted examples:
126+
127+
```sh
128+
bundle exec rspec spec/models/user_spec.rb
129+
bundle exec rspec spec/requests/case_contacts_spec.rb
130+
npm run test -- app/javascript/__tests__/validated_form.test.js
131+
```
132+
133+
Common lint commands:
134+
135+
```sh
136+
bundle exec standardrb
137+
bundle exec erb_lint --lint-all
138+
npm run lint
139+
```
140+
141+
To run the repository's fixer commands:
142+
143+
```sh
144+
bin/lint
145+
```
146+
147+
To lint only files staged or changed on your branch:
148+
149+
```sh
150+
./bin/git_hooks/lint --staged
151+
./bin/git_hooks/lint --unpushed
152+
```
153+
154+
For documentation-only pull requests, there may not be a useful automated test.
155+
In that case, validate links and formatting, then explain that in the pull
156+
request's testing section.
157+
158+
## Testing expectations
159+
160+
Add or update tests for behavior changes. A good pull request includes a test
161+
that would fail without the change and pass with it.
162+
163+
Use the test type that matches the behavior:
164+
165+
- Model specs for validations, associations, scopes, and model-level business
166+
rules.
167+
- Request specs for routes, controller behavior, permissions, and responses.
168+
- System specs for user-visible workflows, JavaScript-driven UI, and role-based
169+
behavior.
170+
- View or component specs for rendering changes that do not need a full browser
171+
flow.
172+
- Policy specs for authorization changes.
173+
- Service, job, mailer, and importer specs for the matching application object.
174+
- Jest tests for JavaScript in `app/javascript`.
175+
176+
For UI changes, run the app locally and include screenshots in the pull request.
177+
If a change affects permissions, test at least one allowed role and one denied
178+
role.
179+
180+
## Pull request conventions
181+
182+
Open a draft pull request when you want early feedback. Mark it ready for review
183+
when the code, tests, and description are ready. If maintainers are using labels,
184+
use or ask for `🚧 Status: WIP` while the pull request is not ready and `Ready`
185+
when it is ready.
186+
187+
Use a short, action-oriented pull request title. Including the issue number is
188+
helpful when the title would otherwise be ambiguous, for example:
189+
190+
```text
191+
6910 - Flesh out contributor guide
192+
```
193+
194+
Fill out the pull request template:
195+
196+
- Link the issue with `Resolves #1234` when the pull request should close it.
197+
- Explain what changed and why.
198+
- List the exact tests and linters you ran.
199+
- Include screenshots for UI changes.
200+
- Note any follow-up work that should become a separate issue.
201+
202+
Before requesting review:
203+
204+
1. Rebase or merge the latest `main` if your branch is stale.
205+
2. Run the relevant tests and linters.
206+
3. Review your own diff for unrelated files, debugging output, and missing docs.
207+
4. Push your branch and open the pull request from your fork.
208+
209+
## Code review
210+
211+
Automated checks run at the bottom of the pull request. Most of them need to pass
212+
before merge. If a CI failure looks flaky, post the failed build link in
213+
`#casa`.
214+
215+
Maintainers may ask for changes. Respond in the pull request thread, push
216+
follow-up commits to the same branch, and re-request review when ready.
217+
Maintainers decide when a pull request is ready to merge.
218+
219+
## Documentation
220+
221+
Update documentation when you add setup steps, commands, workflows, permissions,
222+
background jobs, user-facing behavior, or anything else that future contributors
223+
will need to understand. The [README](README.md), `doc/` directory, and
224+
[wiki](https://github.com/rubyforgood/casa/wiki) are the main documentation
225+
surfaces.

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,8 @@ A CASA (Court Appointed Special Advocate) is a role where a volunteer advocates
4848

4949
We are very happy to have you! CASA and Ruby for Good are committed to welcoming new contributors of all skill levels.
5050

51+
Start with the [contributing guide](./CONTRIBUTING.md) for setup, issue claiming, testing, and pull request expectations.
52+
5153
Find issues to work on [here](https://github.com/rubyforgood/casa/issues?q=is%3Aissue+is%3Aopen+no%3Aassignee) on the issue board. Issues on the [project's](https://github.com/rubyforgood/casa/projects/1) TODO column are another way to browse issues. Check to see that no one is assigned to the issue. Then comment on it to claim the issue. Commenting on an issue doesn't automatically get the issue assigned so double check the comments on an issue to see that no one is requesting assignment.
5254

5355
Pull requests which are not for an issue but which improve the codebase are also welcome! Feel free to make GitHub issues for bugs and improvements. A maintainer will be keeping an eye on issues and PRs every day or three.
@@ -110,7 +112,7 @@ Key libraries: [Hotwire Turbo](https://turbo.hotwired.dev/), [Stimulus](https://
110112

111113
# Developing!
112114
## How to Contribute
113-
See our [contributing guide](./doc/CONTRIBUTING.md) 💖 ✨
115+
See our [contributing guide](./CONTRIBUTING.md) 💖 ✨
114116
## Installation
115117

116118
### Getting Started (Codespaces) 🛠️

‎doc/CONTRIBUTING.md‎

Lines changed: 3 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,6 @@
11
# Contributing
22

3-
We ♥ contributors! By participating in this project, you agree to abide by the Ruby for Good [code of conduct](https://github.com/rubyforgood/code-of-conduct).
3+
The canonical CASA contributor guide now lives at
4+
[../CONTRIBUTING.md](../CONTRIBUTING.md).
45

5-
If you have any questions about an issue, comment on the issue, open a new issue or ask in [the RubyForGood slack](https://join.slack.com/t/rubyforgood/shared_invite/zt-35218k86r-vlIiWqig54c9t~_LkGpQ7Q). CASA has a `#casa` channel in the Slack. Our channel in slack also contains a zoom link for office hours every day office hours are held.
6-
7-
You won't be yelled at for giving your best effort. The worst that can happen is that you'll be politely asked to change something. We appreciate any sort of contributions, and don't want a wall of rules to get in the way of that.
8-
9-
## Contributing Steps
10-
11-
### Issues
12-
13-
All work is organized by issues.
14-
[Find issues here.](https://github.com/rubyforgood/projects/9)
15-
16-
If you would like to contribute, please ask for an issue to be assigned to you.
17-
18-
If you would like to contribute something that is not represented by an issue, please make an issue and assign yourself.
19-
20-
Only take multiple issues if they are related and you can solve all of them at the same time with the same pull request.
21-
22-
### Pull Requests
23-
24-
If you are so inclined, you can open a draft PR as you continue to work on it.
25-
26-
1. Follow [the setup guide](https://github.com/rubyforgood/casa#installation) to get the project working locally.
27-
28-
1. We only accept pull requests with passing tests. To ensure your setup is working before you get started it's great to run the tests first.
29-
30-
- To run the tests use: `bundle exec rspec`
31-
32-
1. Add a test for your change. If you are adding functionality or fixing a bug, you should add a test!
33-
34-
1. Run linters and fix any linting errors that come up.
35-
36-
- From the repo root run: `./bin/git_hooks/lint`
37-
38-
1. Push to your branch/fork and submit a pull request. Include the issue number (ex. `Resolves #1`) in the PR description. This will ensure the issue gets closed automatically when the pull request gets merged.
39-
40-
#### Pull Request Checks
41-
42-
We will try to respond to your PR quickly.
43-
44-
There are scripts that check the code to ensure the code is working. Most of them need to pass. You can see the scripts run at the bottom of your pull request webpage (learn more about the scripts [here](https://github.com/rubyforgood/casa/wiki/Pull-Request-Checks)). You should attempt to fix errors found in the automated testing.
45-
46-
Pull requests are also manually reviewed. We may request changes after a manual review.
47-
48-
Some qualities of good pull requests:
49-
50-
- Small line diff count. Several small pull requests for a large issue are preferred over one big pull request.
51-
- Include tests that fail without your code, and pass with it.
52-
- For pull requests changing UI, make sure the UI matches the rest of the site. Some of our users aren't great with computers and we don't want to make them learn new things if we don't need to.
53-
- Update the documentation, for things like new rails/bash commands. Please include a guide if modifying the code in the future is difficult. For example [editing .docx templates](https://github.com/rubyforgood/casa/wiki/How-to-edit-docx-templates---word-document-court-report) is difficult because the documentation is hard to find and it requires microsoft word.
54-
- If your pull request involves user permissions, use [policy files](https://github.com/varvet/pundit#policies).
55-
- If your pull request has an erb file with complex rails logic inside of it, please use a [decorator](https://medium.com/@kosovacsedad/ruby-on-rails-decorator-design-pattern-b54a1afd03c8).
6+
This file remains so existing links to `doc/CONTRIBUTING.md` continue to work.

‎doc/WSL_SETUP.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,7 @@ Casa's install will also install the correct version of Rails.
149149

150150
1. **Download the project**
151151

152-
**You should create a fork in GitHub if you don't have permission to directly commit to this repo. See our [contributing guide](https://github.com/rubyforgood/casa/blob/main/doc/CONTRIBUTING.md) for more detailed instructions.**
152+
**You should create a fork in GitHub if you don't have permission to directly commit to this repo. See our [contributing guide](https://github.com/rubyforgood/casa/blob/main/CONTRIBUTING.md) for more detailed instructions.**
153153

154154
`git clone <git address>` - use your fork's address if you have one
155155

0 commit comments

Comments
 (0)