From c2c3b35e64e18dd59d0ed2f87604083d0b13d508 Mon Sep 17 00:00:00 2001 From: Dana Sherson Date: Fri, 5 May 2023 17:22:19 +1200 Subject: [PATCH 1/2] Add CONTRBITUTING.md and CODE_OF_CONDUCT.md --- CODE_OF_CONDUCT.md | 78 ++++++++++++++++++++++++++ CONTRIBUTING.md | 136 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 52 +++-------------- 3 files changed, 221 insertions(+), 45 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..96a08960 --- /dev/null +++ b/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 open-source@ackama.com. 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..40530725 --- /dev/null +++ b/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 ` 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. diff --git a/README.md b/README.md index e46370d8..9f914dd8 100644 --- a/README.md +++ b/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 ` 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 From c05e0eb36766b2ad840e4b14f6f1a81f6754bf36 Mon Sep 17 00:00:00 2001 From: Luke Date: Fri, 25 Aug 2023 12:16:44 +1200 Subject: [PATCH 2/2] =?UTF-8?q?ackama=20=E2=86=92=20Ackama?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gareth Jones --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 40530725..44f5568e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -132,5 +132,5 @@ 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 +If you're Ackama staff, ensure any linked Ackama-internal documentation is also up-to-date.