Skip to content

Commit 40e9bee

Browse files
robotdanarobotdana
committed
Add CONTRBITUTING.md and CODE_OF_CONDUCT.md
1 parent f2b8422 commit 40e9bee

File tree

3 files changed

+220
-44
lines changed

3 files changed

+220
-44
lines changed

‎CODE_OF_CONDUCT.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to making participation in our project and
7+
our community a harassment-free experience for everyone, regardless of age, body
8+
size, disability, ethnicity, sex characteristics, gender identity and
9+
expression, level of experience, education, socio-economic status, nationality,
10+
personal appearance, race, religion, or sexual identity and orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
- Using welcoming and inclusive language
18+
- Being respectful of differing viewpoints and experiences
19+
- Gracefully accepting constructive criticism
20+
- Focusing on what is best for the community
21+
- Showing empathy towards other community members
22+
23+
Examples of unacceptable behavior by participants include:
24+
25+
- The use of sexualized language or imagery and unwelcome sexual attention or
26+
advances
27+
- Trolling, insulting/derogatory comments, and personal or political attacks
28+
- Public or private harassment
29+
- Publishing others' private information, such as a physical or electronic
30+
address, without explicit permission
31+
- Other conduct which could reasonably be considered inappropriate in a
32+
professional setting
33+
34+
## Our Responsibilities
35+
36+
Project maintainers are responsible for clarifying the standards of acceptable
37+
behavior and are expected to take appropriate and fair corrective action in
38+
response to any instances of unacceptable behavior.
39+
40+
Project maintainers have the right and responsibility to remove, edit, or reject
41+
comments, commits, code, wiki edits, issues, and other contributions that are
42+
not aligned to this Code of Conduct, or to ban temporarily or permanently any
43+
contributor for other behaviors that they deem inappropriate, threatening,
44+
offensive, or harmful.
45+
46+
## Scope
47+
48+
This Code of Conduct applies both within project spaces and in public spaces
49+
when an individual is representing the project or its community. Examples of
50+
representing a project or community include using an official project e-mail
51+
address, posting via an official social media account, or acting as an appointed
52+
representative at an online or offline event. Representation of a project may be
53+
further defined and clarified by project maintainers.
54+
55+
## Enforcement
56+
57+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
58+
reported by contacting the project team at open-source@ackama.com. All
59+
complaints will be reviewed and investigated and will result in a response that
60+
is deemed necessary and appropriate to the circumstances. The project team is
61+
obligated to maintain confidentiality with regard to the reporter of an
62+
incident. Further details of specific enforcement policies may be posted
63+
separately.
64+
65+
Project maintainers who do not follow or enforce the Code of Conduct in good
66+
faith may face temporary or permanent repercussions as determined by other
67+
members of the project's leadership.
68+
69+
## Attribution
70+
71+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
72+
version 1.4, available at
73+
https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
74+
75+
[homepage]: https://www.contributor-covenant.org
76+
77+
For answers to common questions about this code of conduct, see
78+
https://www.contributor-covenant.org/faq

‎CONTRIBUTING.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Contributing
2+
3+
Although we are always happy to make improvements, we also welcome changes and
4+
improvements from the community!
5+
6+
Have a fix for a problem you've been running into or an idea for a new feature
7+
you think would be useful? Here's what you need to do:
8+
9+
1. [Read and understand the Code of Conduct](#code-of-conduct).
10+
2. Fork this repo (unless you work at ackama) and clone that repo to somewhere
11+
on your machine.
12+
3. [Ensure that you have a working environment](#setting-up-your-environment).
13+
4. Read up on the [architecture of the project](#architecture),
14+
[how to run tests](#tests), and
15+
[the code style we use in this project](#code-style).
16+
5. Cut a new branch and write a failing test for the feature or bugfix you plan
17+
on implementing.
18+
6. [Make sure your branch is well managed as you go along](#managing-your-branch).
19+
7. If this branch fixes an issue, use github's `fixes: #issue_number` when
20+
writing your commit message to link the issue to your pr.
21+
8. Push to your fork and create a pull request.
22+
9. Ensure that the test suite passes CI and make any necessary changes to your
23+
branch to bring it to green.
24+
25+
We will review pull requests fortnightly at our ackama ruby guild meeting. Once
26+
we look at your pull request, we may give you feedback. For instance, we may
27+
suggest some changes to make to your code to fit within the project style or
28+
discuss alternate ways of addressing the issue in question. Assuming we're happy
29+
with everything, we'll then bring your changes into main. Now you're a
30+
contributor!
31+
32+
## Code of Conduct
33+
34+
If this is your first time contributing, please read the [Code of Conduct]. We
35+
want to create a space in which everyone is allowed to contribute, and we
36+
enforce the policies outline in this document.
37+
38+
[code of conduct]:
39+
https://github.com/ackama/rails-template/blob/main/CODE_OF_CONDUCT.md
40+
41+
## Setting up your environment
42+
43+
1. Install
44+
[the most recent ruby version](https://www.ruby-lang.org/en/downloads/) with
45+
the ruby version manager of your choice
46+
2. Run `gem install rails` to get the most recent rails release
47+
3. Install the node version defined in the .node-version file (with nvm if you
48+
prefer)
49+
4. Install yarn v1.21.0 or later
50+
51+
To run tests you'll also need to install
52+
53+
- [PostgreSQL](https://www.postgresql.org/)
54+
- [Chromedriver](https://chromedriver.chromium.org/)
55+
56+
## Architecture
57+
58+
This project works by hooking into the standard Rails
59+
[application templates](https://guides.rubyonrails.org/rails_application_templates.html)
60+
system, with some caveats. The entry point is the
61+
[template.rb](https://github.com/ackama/rails-template/blob/main/template.rb)
62+
file in the root of this repository.
63+
64+
Normally, Rails only allows a single file to be specified as an application
65+
template (i.e. using the `-m <URL>` option). To work around this limitation, the
66+
first step this template performs is a `git clone` of the
67+
`ackama/rails-template` repository to a local temporary directory.
68+
69+
This temporary directory is then added to the `source_paths` of the Rails
70+
generator system, allowing all of its ERb templates and files to be referenced
71+
when the application template script is evaluated.
72+
73+
Rails generators are very lightly documented; what you'll find is that most of
74+
the heavy lifting is done by [Thor](http://whatisthor.com/). Thor is a tool that
75+
allows you to easily perform command line utilities. The most common methods
76+
used by this template are Thor's `copy_file`, `template`, and `gsub_file`. You
77+
can dig into the well-organized and well-documented
78+
[Thor source code](https://github.com/erikhuda/thor) to learn more. If any file
79+
finishes with `.tt`, Thor considers it to be a template and places it in the
80+
destination without the extension `.tt`.
81+
82+
## Tests
83+
84+
this template is tested by building a set of apps with different configuration
85+
and checking each passes the templated linters and tests.
86+
87+
the config is in ci/configs/\*.yml, and is run by ci/bin/build-and-test
88+
89+
```bash
90+
# create new rails app in tmp/builds/enterprise using ci/configs/react.yml as
91+
$ CONFIG_PATH="ci/configs/react.yml" APP_NAME="enterprise" ./ci/bin/build-and-test
92+
```
93+
94+
To add another tested configuration
95+
96+
1. add a file in ci/configs
97+
2. add it to the lists in .github/workflows/ci.yml
98+
99+
## Code style
100+
101+
Rubocop is configured for this repo and is run as part of CI. Run rubocop
102+
locally via the usual method:
103+
104+
```
105+
$ bundle install
106+
$ bundle exec rubocop # optionally adding -a or -A for autofixes
107+
```
108+
109+
Prettier is used to manage the style for json, js/jsx/ts/tsx, css/scss, and
110+
md/markdown files, and is run as part of CI. Run prettier localy via yarn
111+
112+
```
113+
$ yarn install
114+
$ yarn run format-check # or `yarn run format-fix` for autofixes
115+
```
116+
117+
## Managing your branch
118+
119+
- Use well-crafted commit messages, providing context if possible.
120+
- Squash "WIP" commits and remove merge commits by rebasing your branch against
121+
`main`. We try to keep our commit history as clean as possible.
122+
123+
## Documentation
124+
125+
As you navigate the codebase, you may notice certain classes and methods that
126+
are prefaced with inline documentation.
127+
128+
If your changes end up extending or updating the API, it helps greatly to update
129+
the docs at the same time for future developers and other readers of the source
130+
code.
131+
132+
Ensure any changes to features documented in the README.md or this
133+
CONTRIBUTING.md have their documentation updated as necessary.
134+
135+
If you're ackama staff, ensure any linked ackama-internal documentation is also
136+
up-to-date.

‎README.md‎

Lines changed: 6 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -236,51 +236,13 @@ $ rails new my-awesome-app
236236

237237
## Contributing
238238

239-
This project works by hooking into the standard Rails
240-
[application templates](https://guides.rubyonrails.org/rails_application_templates.html)
241-
system, with some caveats. The entry point is the
242-
[template.rb](https://github.com/ackama/rails-template/blob/main/template.rb)
243-
file in the root of this repository.
244-
245-
Normally, Rails only allows a single file to be specified as an application
246-
template (i.e. using the `-m <URL>` option). To work around this limitation, the
247-
first step this template performs is a `git clone` of the
248-
`ackama/rails-template` repository to a local temporary directory.
249-
250-
This temporary directory is then added to the `source_paths` of the Rails
251-
generator system, allowing all of its ERb templates and files to be referenced
252-
when the application template script is evaluated.
253-
254-
Rails generators are very lightly documented; what you'll find is that most of
255-
the heavy lifting is done by [Thor](http://whatisthor.com/). Thor is a tool that
256-
allows you to easily perform command line utilities. The most common methods
257-
used by this template are Thor's `copy_file`, `template`, and `gsub_file`. You
258-
can dig into the well-organized and well-documented
259-
[Thor source code](https://github.com/erikhuda/thor) to learn more. If any file
260-
finishes with `.tt`, Thor considers it to be a template and places it in the
261-
destination without the extension `.tt`.
239+
If this is your first time contributing, please read the [Code of Conduct] and
240+
the [Contributing guide].
262241

263-
```bash
264-
# create new rails app in tmp/builds/enterprise using ci/configs/react.yml as
265-
# configuration
266-
$ CONFIG_PATH="ci/configs/react.yml" APP_NAME="enterprise" ./ci/bin/build-and-test
267-
268-
# or do it manually:
269-
#
270-
# CONFIG_PATH must be relative to the dir that the rails app is created in
271-
# because the template is run by `rails new` which uses the rails app dir as
272-
# it's working dir, hence the `../` at the start.
273-
#
274-
$ rm -rf mydemoapp && CONFIG_PATH="../ci/configs/react.yml" rails new mydemoapp -d postgresql --skip-javascript -m ./template.rb
275-
```
276-
277-
Rubocop is configured for this repo and is run as part of CI. Run rubocop
278-
locally via the usual method:
279-
280-
```
281-
$ bundle install
282-
$ bundle exec rubocop # optionally adding -A for autofixes
283-
```
242+
[code of conduct]:
243+
https://github.com/ackama/rails-template/blob/main/CODE_OF_CONDUCT.md
244+
[contributing guide]:
245+
https://github.com/ackama/rails-template/blob/main/CONTRIBUTING.md
284246

285247
## Credits
286248

0 commit comments

Comments
 (0)