Add CONTRIBUTING.md and CODE_OF_CONDUCT.md

CODE_OF_CONDUCT.md

@@ -0,0 +1,78 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and
+expression, level of experience, education, socio-economic status, nationality,
+personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, or to ban temporarily or permanently any
+contributor for other behaviors that they deem inappropriate, threatening,
+offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [email protected]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an
+incident. Further details of specific enforcement policies may be posted
+separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.4, available at
+https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

CONTRIBUTING.md

@@ -0,0 +1,136 @@
+# Contributing
+
+Although we are always happy to make improvements, we also welcome changes and
+improvements from the community!
+
+Have a fix for a problem you've been running into or an idea for a new feature
+you think would be useful? Here's what you need to do:
+
+1. [Read and understand the Code of Conduct](#code-of-conduct).
+2. Fork this repo (unless you work at Ackama) and clone that repo to somewhere
+   on your machine.
+3. [Ensure that you have a working environment](#setting-up-your-environment).
+4. Read up on the [architecture of the project](#architecture),
+   [how to run tests](#tests), and
+   [the code style we use in this project](#code-style).
+5. Cut a new branch and write a failing test for the feature or bugfix you plan
+   on implementing.
+6. [Make sure your branch is well managed as you go along](#managing-your-branch).
+7. If this branch fixes an issue, use github's `fixes: #issue_number` when
+   writing your commit message to link the issue to your pr.
+8. Push to your fork and create a pull request.
+9. Ensure that the test suite passes CI and make any necessary changes to your
+   branch to bring it to green.
+
+We aim to review pull requests at our internal Ackama fortnightly ruby guild
+meeting. Once we look at your pull request, we may give you feedback. For
+instance, we may suggest some changes to make to your code to fit within the
+project style or discuss alternate ways of addressing the issue in question.
+Assuming we're happy with everything, we'll then bring your changes into main.
+Now you're a contributor!
+
+## Code of Conduct
+
+If this is your first time contributing, please read the [Code of Conduct]. We
+want to create a space in which everyone is allowed to contribute, and we
+enforce the policies outline in this document.
+
+[code of conduct]:
+  https://github.com/ackama/rails-template/blob/main/CODE_OF_CONDUCT.md
+
+## Setting up your environment
+
+1. Install
+   [the most recent ruby version](https://www.ruby-lang.org/en/downloads/) with
+   the ruby version manager of your choice
+2. Run `gem install rails` to get the most recent rails release
+3. Install the node version defined in the `.node-version` file with the node
+   version manager of your choice
+4. Install yarn v1
+
+To run tests you'll also need to install
+
+- [PostgreSQL](https://www.postgresql.org/)
+- [Chromedriver](https://chromedriver.chromium.org/)
+
+## Architecture
+
+This project works by hooking into the standard Rails
+[application templates](https://guides.rubyonrails.org/rails_application_templates.html)
+system, with some caveats. The entry point is the
+[template.rb](https://github.com/ackama/rails-template/blob/main/template.rb)
+file in the root of this repository.
+
+Normally, Rails only allows a single file to be specified as an application
+template (i.e. using the `-m <URL>` option). To work around this limitation, the
+first step this template performs is a `git clone` of the
+`ackama/rails-template` repository to a local temporary directory.
+
+This temporary directory is then added to the `source_paths` of the Rails
+generator system, allowing all of its ERb templates and files to be referenced
+when the application template script is evaluated.
+
+Rails generators are very lightly documented; what you'll find is that most of
+the heavy lifting is done by [Thor](http://whatisthor.com/). Thor is a tool that
+allows you to easily perform command line utilities. The most common methods
+used by this template are Thor's `copy_file`, `template`, and `gsub_file`. You
+can dig into the well-organized and well-documented
+[Thor source code](https://github.com/erikhuda/thor) to learn more. If any file
+finishes with `.tt`, Thor considers it to be a template and places it in the
+destination without the extension `.tt`.
+
+## Tests
+
+this template is tested by building a set of apps with different configuration
+and checking each passes the templated linters and tests.
+
+the config is in ci/configs/\*.yml, and is run by ci/bin/build-and-test
+
+```bash
+# create new rails app in tmp/builds/enterprise using ci/configs/react.yml as
+$ CONFIG_PATH="ci/configs/react.yml" APP_NAME="enterprise" ./ci/bin/build-and-test
+```
+
+To add another tested configuration
+
+1. add a file in ci/configs
+2. add it to the lists in .github/workflows/ci.yml
+
+## Code style
+
+Rubocop is configured for this repo and is run as part of CI. Run rubocop
+locally via the usual method:
+
+```
+$ bundle install
+$ bundle exec rubocop # optionally adding -a or -A for autofixes
+```
+
+Prettier is used to manage the style for json, js/jsx/ts/tsx, css/scss, and
+md/markdown files, and is run as part of CI. Run prettier localy via yarn
+
+```
+$ yarn install
+$ yarn run format-check # or `yarn run format-fix` for autofixes
+```
+
+## Managing your branch
+
+- Use well-crafted commit messages, providing context if possible.
+- Squash "WIP" commits and remove merge commits by rebasing your branch against
+  `main`. We try to keep our commit history as clean as possible.
+
+## Documentation
+
+As you navigate the codebase, you may notice certain classes and methods that
+are prefaced with inline documentation.
+
+If your changes end up extending or updating the API, it helps greatly to update
+the docs at the same time for future developers and other readers of the source
+code.
+
+Ensure any changes to features documented in the README.md or this
+CONTRIBUTING.md have their documentation updated as necessary.
+
+If you're Ackama staff, ensure any linked Ackama-internal documentation is also
+up-to-date.

README.md

@@ -154,7 +154,7 @@ our other templates:
 Before running this template, you must have the following installed on your
 machine:
 
-- Yarn v1.21.0 or later
+- Yarn v1
 - Rails 7.1.x
 
 The following are not strictly required to run the template but you will need it
@@ -241,51 +241,13 @@ $ rails new my-awesome-app
 
 ## Contributing
 
-This project works by hooking into the standard Rails
-[application templates](https://guides.rubyonrails.org/rails_application_templates.html)
-system, with some caveats. The entry point is the
-[template.rb](https://github.com/ackama/rails-template/blob/main/template.rb)
-file in the root of this repository.
-
-Normally, Rails only allows a single file to be specified as an application
-template (i.e. using the `-m <URL>` option). To work around this limitation, the
-first step this template performs is a `git clone` of the
-`ackama/rails-template` repository to a local temporary directory.
-
-This temporary directory is then added to the `source_paths` of the Rails
-generator system, allowing all of its ERb templates and files to be referenced
-when the application template script is evaluated.
-
-Rails generators are very lightly documented; what you'll find is that most of
-the heavy lifting is done by [Thor](http://whatisthor.com/). Thor is a tool that
-allows you to easily perform command line utilities. The most common methods
-used by this template are Thor's `copy_file`, `template`, and `gsub_file`. You
-can dig into the well-organized and well-documented
-[Thor source code](https://github.com/erikhuda/thor) to learn more. If any file
-finishes with `.tt`, Thor considers it to be a template and places it in the
-destination without the extension `.tt`.
+If this is your first time contributing, please read the [Code of Conduct] and
+the [Contributing guide].
 
-```bash
-# create new rails app in tmp/builds/enterprise using ci/configs/react.yml as
-# configuration
-$ CONFIG_PATH="ci/configs/react.yml" APP_NAME="enterprise" ./ci/bin/build-and-test
-
-# or do it manually:
-#
-# CONFIG_PATH must be relative to the dir that the rails app is created in
-# because the template is run by `rails new` which uses the rails app dir as
-# it's working dir, hence the `../` at the start.
-#
-$ rm -rf mydemoapp && CONFIG_PATH="../ci/configs/react.yml" rails new mydemoapp -d postgresql --skip-javascript --skip-docker -m ./template.rb
-```
-
-Rubocop is configured for this repo and is run as part of CI. Run rubocop
-locally via the usual method:
-
-```
-$ bundle install
-$ bundle exec rubocop # optionally adding -A for autofixes
-```
+[code of conduct]:
+  https://github.com/ackama/rails-template/blob/main/CODE_OF_CONDUCT.md
+[contributing guide]:
+  https://github.com/ackama/rails-template/blob/main/CONTRIBUTING.md
 
 ## Credits