-
Notifications
You must be signed in to change notification settings - Fork 25
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[#322] Add home, contribution guide, and testing section to github wiki
- Loading branch information
1 parent
f6f2eb7
commit f3779f4
Showing
5 changed files
with
202 additions
and
11 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
117 changes: 117 additions & 0 deletions
117
.template/addons/github/.github/wiki/Contribution_Guide.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,117 @@ | ||
## How to contribute | ||
|
||
### Template structure | ||
|
||
``` | ||
. | ||
├── .template | ||
│ ├── addons | ||
│ │ └── docker | ||
│ │ ├── ... | ||
│ │ └── template.rb | ||
│ └── variants | ||
│ ├── api | ||
│ │ ├── ... | ||
│ │ └── template.rb | ||
│ └── web | ||
│ ├── ... | ||
│ └── template.rb | ||
├── app | ||
├── bin | ||
├── config | ||
├── spec | ||
├── ... | ||
├── README.md | ||
├── README.md.tt | ||
└── template.rb | ||
``` | ||
|
||
We keep the Rails-app-like structure. On the root, there are base project file templates. | ||
Other files including the template options are in `.template` folder. | ||
|
||
There are 2 kinds of the template options: | ||
|
||
1. **Variants** - For the app main options, which are `web` and `api`. | ||
|
||
2. **Addons** - For other extra options that we can add to the project like `docker` or `bootstrap`, | ||
use the prompt `ask` to generate a question before generating the project. | ||
|
||
### Template files | ||
|
||
There are 2 template file types: | ||
|
||
1. **`.tt` files** | ||
|
||
This file is used for templating the whole new file. | ||
In case if we want to create a new file that Rails has not generated. | ||
|
||
2. **`.rb` files** | ||
|
||
This is used for modifying the files that Rails has generated. | ||
The file name should be the same as on the generated app. | ||
If it is not a ruby file, append the `.rb` as an extension e.g. `Gemfile.rb` | ||
|
||
### Template specs | ||
|
||
We are using [Serverspec](https://serverspec.org/) to test the template. | ||
For any changes made, you **must** add a spec for it. | ||
|
||
Test files are located under `.template/spec` folder | ||
|
||
``` | ||
. | ||
├── ... | ||
├── .template | ||
│ ├── ... | ||
│ ├── spec | ||
│ │ └── addons | ||
│ │ │ └── base | ||
│ │ │ │ └── docker | ||
│ │ │ │ │ ├── ... | ||
│ │ │ │ │ └── template_spec.rb | ||
│ │ │ │ └── semaphore | ||
│ │ │ │ │ ├── ... | ||
│ │ │ │ │ └── template_spec.rb | ||
│ │ │ └── variants | ||
│ │ │ │ └── web | ||
│ │ │ │ │ └── boostrap | ||
│ │ │ │ │ ├── ... | ||
│ │ │ │ │ └── template_spec.rb | ||
│ │ │ │ └── api | ||
│ │ │ │ │ └── addon | ||
│ │ │ │ │ ├── ... | ||
│ │ │ │ │ └── template_spec.rb | ||
│ │ └── base | ||
│ │ │ ├── ... | ||
│ │ │ └── template_spec.rb | ||
│ │ └── variants | ||
│ │ │ └── web | ||
│ │ │ │ ├── ... | ||
│ │ │ │ └── template_spec.rb | ||
│ │ │ └── api | ||
│ │ │ │ ├── ... | ||
│ │ │ │ └── template_spec.rb | ||
``` | ||
|
||
### Template Strings | ||
|
||
When using template string with heredoc, use the proper name following the file type / content. | ||
|
||
This provides the meaningful context to the content and some IDEs also support to highlight the content depending on the type. | ||
|
||
- `DOCKERFILE` | ||
- `ERB` | ||
- `HTML` | ||
- `IGNORE` - For any ignore file e.g. `.gitignore`, `.eslintignore` | ||
- `JAVASCRIPT` | ||
- `JSON` | ||
- `PROCFILE` | ||
- `RUBY` | ||
- `SCSS` | ||
- `SHELL` | ||
|
||
For other files that are not fit the types above, use the extension as the name | ||
e.g. `TOOL_VERSION` for `.tool-version` file. | ||
|
||
For the normal string, name it after the content | ||
e.g. `ERROR` for template error message. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,65 @@ | ||
> *Insert information about your project here!* | ||
<p align="center"> | ||
<img alt="Nimble logo" src="https://assets.nimblehq.co/logo/light/logo-light-text-320.png" /> | ||
</p> | ||
|
||
<p align="center"> | ||
<strong>Rails Templates</strong> | ||
</p> | ||
|
||
|
||
--- | ||
|
||
Our templates offer a rich boilerplate to jump start Rails-based application development and are based on our experience | ||
with building complex applications over the years. | ||
|
||
## Get Started | ||
|
||
### Requirements | ||
|
||
- Install ruby and set your local ruby version to `3.0.1` | ||
- Install rails `7.0.1` | ||
- Install node `16.13.2` (For creating web application) | ||
|
||
> 📝 If running on Apple M1, to build docker image, please make sure to set platform to AMD64 by `export DOCKER_DEFAULT_PLATFORM=linux/amd64` | ||
### Use the template | ||
|
||
In order to use the template, initialize a new app with the following parameters: | ||
|
||
```sh | ||
rails new <app_name> -m https://raw.githubusercontent.com/nimblehq/rails-templates/main/template.rb | ||
``` | ||
|
||
Supported template options: | ||
- `--api` - create an api-only application | ||
|
||
To apply the template on an existing application, run following rails command: | ||
|
||
```sh | ||
rails app:template LOCATION=https://raw.githubusercontent.com/nimblehq/rails-templates/main/template.rb | ||
|
||
# To apply on an api application | ||
rails app:template LOCATION=https://raw.githubusercontent.com/nimblehq/rails-templates/main/template.rb API=true | ||
|
||
|
||
|
||
# To apply a specific addon | ||
rails app:template LOCATION=https://raw.githubusercontent.com/nimblehq/rails-templates/main/template.rb ADDON=<addon name> | ||
``` | ||
|
||
Available Addons: | ||
- `docker` | ||
- `nginx` | ||
- `phrase` | ||
- `semaphore` | ||
- `bootstrap` | ||
- `slim` | ||
- `devise` | ||
|
||
After the template finishes generating all the files, run the following command to start the rails server. | ||
|
||
```sh | ||
make dev | ||
``` | ||
|
||
Read more about Rails Application Template in the [official Rails Guides](https://guides.rubyonrails.org/rails_application_templates.html). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
## Testing the Template | ||
|
||
To run [RuboCop](https://github.com/rubocop/rubocop) against the template: | ||
|
||
|
||
```sh | ||
.template/bin/rubocop | ||
|
||
|
||
bla bla bla | ||
``` | ||
|
||
Any RuboCop command options can be passed: | ||
|
||
|
||
```sh | ||
# Run Ru`boCop with auto correct | ||
.template/bin/rubocop -a | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters