Skip to content

Commit c2c3b35

Browse files
robotdanaG-Rath
robotdana
authored and
G-Rath
committed
Add CONTRBITUTING.md and CODE_OF_CONDUCT.md
1 parent 2c31cef commit c2c3b35

File tree

3 files changed

+221
-45
lines changed

3 files changed

+221
-45
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 aim to review pull requests at our internal Ackama fortnightly ruby guild
26+
meeting. Once we look at your pull request, we may give you feedback. For
27+
instance, we may suggest some changes to make to your code to fit within the
28+
project style or discuss alternate ways of addressing the issue in question.
29+
Assuming we're happy with everything, we'll then bring your changes into main.
30+
Now you're a 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 the node
48+
version manager of your choice
49+
4. Install yarn v1
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: 7 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -154,7 +154,7 @@ our other templates:
154154
Before running this template, you must have the following installed on your
155155
machine:
156156

157-
- Yarn v1.21.0 or later
157+
- Yarn v1
158158
- Rails 7.1.x
159159

160160
The following are not strictly required to run the template but you will need it
@@ -241,51 +241,13 @@ $ rails new my-awesome-app
241241

242242
## Contributing
243243

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

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

290252
## Credits
291253

0 commit comments

Comments
 (0)