Introduce markdownlint for guides
This is a follow up to rails#47186, this time for all markdown content. [markdownlint](https://github.com/markdownlint/markdownlint) is an excellent tool, and I've found it very useful for finding issues in the guides. Many of the rules are common style issues I'm correcting on PRs, so it will be nice to have that automated. We should also be able to use the same config with our editors, so that errors show up in real-time 🙏 and will update the contributing docs once this gets merged with how to debug and use mdl appropriately.
This commit is contained in:
parent
99096b88ae
commit
c3f2b545f8
24
.github/workflows/mdl.yml
vendored
Normal file
24
.github/workflows/mdl.yml
vendored
Normal file
@ -0,0 +1,24 @@
|
||||
name: Markdown Lint [Guides]
|
||||
|
||||
on: [pull_request]
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
mdl:
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
BUNDLE_ONLY: mdl
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Set up Ruby 3.2
|
||||
uses: ruby/setup-ruby@v1
|
||||
with:
|
||||
ruby-version: 3.2
|
||||
bundler-cache: true
|
||||
|
||||
- name: Run mdl
|
||||
run: bundle exec rake -f guides/Rakefile guides:lint
|
1
.mdlrc
Normal file
1
.mdlrc
Normal file
@ -0,0 +1 @@
|
||||
style "#{File.dirname(__FILE__)}/.mdlrc.rb"
|
23
.mdlrc.rb
Normal file
23
.mdlrc.rb
Normal file
@ -0,0 +1,23 @@
|
||||
# frozen_string_literal: true
|
||||
|
||||
all
|
||||
|
||||
exclude_rule "MD003"
|
||||
exclude_rule "MD004"
|
||||
exclude_rule "MD005"
|
||||
exclude_rule "MD006"
|
||||
exclude_rule "MD007"
|
||||
exclude_rule "MD012"
|
||||
exclude_rule "MD014"
|
||||
exclude_rule "MD024"
|
||||
exclude_rule "MD026"
|
||||
exclude_rule "MD033"
|
||||
exclude_rule "MD034"
|
||||
exclude_rule "MD036"
|
||||
exclude_rule "MD040"
|
||||
exclude_rule "MD041"
|
||||
|
||||
rule "MD013", line_length: 2000, ignore_code_blocks: true
|
||||
# rule "MD024", allow_different_nesting: true # This did not work as intended, see action_cable_overview.md
|
||||
rule "MD029", style: :ordered
|
||||
# rule "MD046", style: :consistent # default (:fenced)
|
5
Gemfile
5
Gemfile
@ -49,6 +49,11 @@ group :rubocop do
|
||||
gem "rubocop-md", require: false
|
||||
end
|
||||
|
||||
group :mdl do
|
||||
gem "mdl", require: false
|
||||
gem "rake", ">= 13", require: false
|
||||
end
|
||||
|
||||
group :doc do
|
||||
gem "sdoc", ">= 2.6.0"
|
||||
gem "rdoc", "~> 6.5"
|
||||
|
23
Gemfile.lock
23
Gemfile.lock
@ -160,6 +160,8 @@ GEM
|
||||
regexp_parser (>= 1.5, < 3.0)
|
||||
xpath (~> 3.2)
|
||||
cgi (0.3.6)
|
||||
chef-utils (18.1.29)
|
||||
concurrent-ruby
|
||||
concurrent-ruby (1.1.10)
|
||||
connection_pool (2.3.0)
|
||||
crack (0.4.5)
|
||||
@ -275,6 +277,10 @@ GEM
|
||||
railties (>= 6.0.0)
|
||||
json (2.6.3)
|
||||
jwt (2.6.0)
|
||||
kramdown (2.4.0)
|
||||
rexml
|
||||
kramdown-parser-gfm (1.1.0)
|
||||
kramdown (~> 2.0)
|
||||
libxml-ruby (4.0.0)
|
||||
listen (3.8.0)
|
||||
rb-fsevent (~> 0.10, >= 0.10.3)
|
||||
@ -289,6 +295,12 @@ GEM
|
||||
net-smtp
|
||||
marcel (1.0.2)
|
||||
matrix (0.4.2)
|
||||
mdl (0.12.0)
|
||||
kramdown (~> 2.3)
|
||||
kramdown-parser-gfm (~> 1.1)
|
||||
mixlib-cli (~> 2.1, >= 2.1.1)
|
||||
mixlib-config (>= 2.2.1, < 4)
|
||||
mixlib-shellout
|
||||
memoist (0.16.2)
|
||||
mini_magick (4.12.0)
|
||||
mini_mime (1.1.2)
|
||||
@ -303,6 +315,11 @@ GEM
|
||||
minitest (>= 5.0)
|
||||
minitest-server (1.0.7)
|
||||
minitest (~> 5.16)
|
||||
mixlib-cli (2.1.8)
|
||||
mixlib-config (3.0.27)
|
||||
tomlrb
|
||||
mixlib-shellout (3.2.7)
|
||||
chef-utils
|
||||
mono_logger (1.1.1)
|
||||
msgpack (1.6.0)
|
||||
multi_json (1.15.0)
|
||||
@ -327,7 +344,7 @@ GEM
|
||||
racc (~> 1.4)
|
||||
os (1.1.4)
|
||||
parallel (1.22.1)
|
||||
parser (3.2.0.0)
|
||||
parser (3.2.1.1)
|
||||
ast (~> 2.4.1)
|
||||
path_expander (1.1.1)
|
||||
pg (1.4.5)
|
||||
@ -407,7 +424,7 @@ GEM
|
||||
rubocop-ast (>= 1.26.0, < 2.0)
|
||||
ruby-progressbar (~> 1.7)
|
||||
unicode-display_width (>= 2.4.0, < 3.0)
|
||||
rubocop-ast (1.27.0)
|
||||
rubocop-ast (1.28.0)
|
||||
parser (>= 3.2.1.0)
|
||||
rubocop-md (1.2.0)
|
||||
rubocop (>= 1.0)
|
||||
@ -489,6 +506,7 @@ GEM
|
||||
thor (1.2.1)
|
||||
tilt (2.0.11)
|
||||
timeout (0.3.2)
|
||||
tomlrb (2.0.3)
|
||||
trailblazer-option (0.1.2)
|
||||
turbo-rails (1.3.2)
|
||||
actionpack (>= 6.0.0)
|
||||
@ -558,6 +576,7 @@ DEPENDENCIES
|
||||
json (>= 2.0.0)
|
||||
libxml-ruby
|
||||
listen (~> 3.3)
|
||||
mdl
|
||||
minitest (>= 5.15.0)
|
||||
minitest-bisect
|
||||
minitest-ci
|
||||
|
@ -24,6 +24,14 @@ namespace :guides do
|
||||
end
|
||||
end
|
||||
|
||||
desc "Lint guides, using `mdl`"
|
||||
task :lint do
|
||||
require "mdl"
|
||||
all = Dir.glob("#{__dir__}/source/*.md")
|
||||
files = all - Dir.glob("#{__dir__}/**/*_release_notes.md") # Ignore release notes
|
||||
MarkdownLint.run files
|
||||
end
|
||||
|
||||
# Validate guides -------------------------------------------------------------------------
|
||||
desc 'Validate guides, use ONLY=foo to process just "foo.html"'
|
||||
task :validate do
|
||||
|
@ -88,8 +88,7 @@ singularizing) both regular and irregular words. When using class names composed
|
||||
of two or more words, the model class name should follow the Ruby conventions,
|
||||
using the CamelCase form, while the table name must use the snake_case form. Examples:
|
||||
|
||||
* Model Class - Singular with the first letter of each word capitalized (e.g.,
|
||||
`BookClub`).
|
||||
* Model Class - Singular with the first letter of each word capitalized (e.g., `BookClub`).
|
||||
* Database Table - Plural with underscores separating words (e.g., `book_clubs`).
|
||||
|
||||
| Model / Class | Table / Schema |
|
||||
|
@ -265,6 +265,7 @@ When generating the filter parameter, it will use the model name as a prefix. E.
|
||||
```ruby
|
||||
config.active_record.encryption.add_to_filter_parameters = false
|
||||
```
|
||||
|
||||
In case you want exclude specific columns from this automatic filtering, add them to `config.active_record.encryption.excluded_from_filter_parameters`.
|
||||
|
||||
### Encoding
|
||||
@ -534,6 +535,7 @@ ActiveRecord::Encryption.without_encryption do
|
||||
...
|
||||
end
|
||||
```
|
||||
|
||||
This means that reading encrypted text will return the ciphertext, and saved content will be stored unencrypted.
|
||||
|
||||
##### Protect Encrypted Data
|
||||
@ -545,4 +547,5 @@ ActiveRecord::Encryption.protecting_encrypted_data do
|
||||
...
|
||||
end
|
||||
```
|
||||
|
||||
This can be handy if you want to protect encrypted data while still running arbitrary code against it (e.g. in a Rails console).
|
||||
|
@ -23,10 +23,8 @@ At this time the following features are supported:
|
||||
|
||||
* Multiple writer databases and a replica for each
|
||||
* Automatic connection switching for the model you're working with
|
||||
* Automatic swapping between the writer and replica depending on the HTTP verb
|
||||
and recent writes
|
||||
* Rails tasks for creating, dropping, migrating, and interacting with the multiple
|
||||
databases
|
||||
* Automatic swapping between the writer and replica depending on the HTTP verb and recent writes
|
||||
* Rails tasks for creating, dropping, migrating, and interacting with the multiple databases
|
||||
|
||||
The following features are not (yet) supported:
|
||||
|
||||
|
@ -183,6 +183,7 @@ amazon:
|
||||
server_side_encryption: "" # 'aws:kms' or 'AES256'
|
||||
cache_control: "private, max-age=<%= 1.day.to_i %>"
|
||||
```
|
||||
|
||||
TIP: Set sensible client HTTP timeouts and retry limits for your application. In certain failure scenarios, the default AWS client configuration may cause connections to be held for up to several minutes and lead to request queuing.
|
||||
|
||||
Add the [`aws-sdk-s3`](https://github.com/aws/aws-sdk-ruby) gem to your `Gemfile`:
|
||||
|
@ -548,6 +548,7 @@ Some common modules you might want to add:
|
||||
self.cache_store = :mem_cache_store
|
||||
end
|
||||
```
|
||||
|
||||
Rails does *not* pass this configuration automatically.
|
||||
|
||||
The best place to add a module is in your `ApplicationController`, but you can
|
||||
|
@ -113,26 +113,17 @@ with a built-in helper. In the source the generated code looked like this:
|
||||
|
||||
The query string strategy has several disadvantages:
|
||||
|
||||
1. **Not all caches will reliably cache content where the filename only differs by
|
||||
query parameters**
|
||||
1. **Not all caches will reliably cache content where the filename only differs by query parameters**
|
||||
|
||||
[Steve Souders recommends](https://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/),
|
||||
"...avoiding a querystring for cacheable resources". He found that in this
|
||||
case 5-20% of requests will not be cached. Query strings in particular do not
|
||||
work at all with some CDNs for cache invalidation.
|
||||
[Steve Souders recommends][], "...avoiding a querystring for cacheable resources". He found that in this case 5-20% of requests will not be cached. Query strings in particular do not work at all with some CDNs for cache invalidation.
|
||||
|
||||
2. **The file name can change between nodes in multi-server environments.**
|
||||
|
||||
The default query string in Rails 2.x is based on the modification time of
|
||||
the files. When assets are deployed to a cluster, there is no guarantee that the
|
||||
timestamps will be the same, resulting in different values being used depending
|
||||
on which server handles the request.
|
||||
The default query string in Rails 2.x is based on the modification time of the files. When assets are deployed to a cluster, there is no guarantee that the timestamps will be the same, resulting in different values being used depending on which server handles the request.
|
||||
|
||||
3. **Too much cache invalidation**
|
||||
|
||||
When static assets are deployed with each new release of code, the mtime
|
||||
(time of last modification) of _all_ these files changes, forcing all remote
|
||||
clients to fetch them again, even when the content of those assets has not changed.
|
||||
When static assets are deployed with each new release of code, the mtime (time of last modification) of _all_ these files changes, forcing all remote clients to fetch them again, even when the content of those assets has not changed.
|
||||
|
||||
Fingerprinting fixes these problems by avoiding query strings, and by ensuring
|
||||
that filenames are consistent based on their content.
|
||||
@ -147,7 +138,7 @@ More reading:
|
||||
* [Revving Filenames: don't use querystring](http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/)
|
||||
|
||||
[`config.assets.digest`]: configuring.html#config-assets-digest
|
||||
|
||||
[Steve Souders recommends]: https://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/
|
||||
|
||||
How to Use the Asset Pipeline
|
||||
-----------------------------
|
||||
@ -777,6 +768,7 @@ Note the following caveats:
|
||||
```ruby
|
||||
config.assets.prefix = "/dev-assets"
|
||||
```
|
||||
|
||||
* The asset precompile task in your deployment tool (_e.g.,_ Capistrano) should
|
||||
be disabled.
|
||||
* Any necessary compressors or minifiers must be available on your development
|
||||
@ -1141,6 +1133,7 @@ and any other environments you define with production behavior (not
|
||||
`application.rb`).
|
||||
|
||||
TIP: For further details have a look at the docs of your production web server:
|
||||
|
||||
- [Apache](https://tn123.org/mod_xsendfile/)
|
||||
- [NGINX](https://www.nginx.com/resources/wiki/start/topics/examples/xsendfile/)
|
||||
|
||||
|
@ -2626,6 +2626,7 @@ def check_credit_limit(book)
|
||||
throw(:abort) if limit_reached?
|
||||
end
|
||||
```
|
||||
|
||||
NOTE: These callbacks are called only when the associated objects are added or removed through the association collection:
|
||||
|
||||
```ruby
|
||||
|
@ -486,6 +486,7 @@ $ bin/rails generate model Oops
|
||||
create test/models/oops_test.rb
|
||||
create test/fixtures/oops.yml
|
||||
```
|
||||
|
||||
```bash
|
||||
$ bin/rails destroy model Oops
|
||||
invoke active_record
|
||||
|
@ -437,6 +437,7 @@ For MySQL and PostgreSQL, it is sufficient to run:
|
||||
$ cd activerecord
|
||||
$ bundle exec rake db:mysql:build
|
||||
```
|
||||
|
||||
Or:
|
||||
|
||||
```bash
|
||||
|
@ -73,6 +73,7 @@ NOTE: The Rails error-reporter will always call registered subscribers, regardle
|
||||
There are three ways you can use the error reporter:
|
||||
|
||||
#### Reporting and Swallowing Errors
|
||||
|
||||
[`Rails.error.handle`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-handle) will report any error raised within the block. It will then **swallow** the error, and the rest of your code outside the block will continue as normal.
|
||||
|
||||
```ruby
|
||||
@ -92,6 +93,7 @@ end
|
||||
```
|
||||
|
||||
#### Reporting and Re-raising Errors
|
||||
|
||||
[`Rails.error.record`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-record) will report errors to all registered subscribers and then re-raise the error, meaning that the rest of your code won't execute.
|
||||
|
||||
```ruby
|
||||
@ -104,6 +106,7 @@ end
|
||||
If no error is raised in the block, `Rails.error.record` will return the result of the block.
|
||||
|
||||
#### Manually Reporting Errors
|
||||
|
||||
You can also manually report errors by calling [`Rails.error.report`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-report):
|
||||
|
||||
```ruby
|
||||
|
@ -366,6 +366,7 @@ Rails works around this issue by emulating other methods over POST through a com
|
||||
<button type="submit" name="button">Update</button>
|
||||
</form>
|
||||
```
|
||||
|
||||
[formmethod]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-formmethod
|
||||
[button-name]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-name
|
||||
[button-value]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-value
|
||||
|
@ -543,6 +543,7 @@ You will then need to change existing image transformation code to the
|
||||
`image_processing` macros, and replace ImageMagick's options with libvips' options.
|
||||
|
||||
#### Replace resize with resize_to_limit
|
||||
|
||||
```diff
|
||||
- variant(resize: "100x")
|
||||
+ variant(resize_to_limit: [100, nil])
|
||||
@ -551,6 +552,7 @@ You will then need to change existing image transformation code to the
|
||||
If you don't do this, when you switch to vips you will see this error: `no implicit conversion to float from string`.
|
||||
|
||||
#### Use an array when cropping
|
||||
|
||||
```diff
|
||||
- variant(crop: "1920x1080+0+0")
|
||||
+ variant(crop: [0, 0, 1920, 1080])
|
||||
@ -568,6 +570,7 @@ Vips is more strict than ImageMagick when it comes to cropping:
|
||||
If you don't do this when migrating to vips, you will see the following error: `extract_area: bad extract area`
|
||||
|
||||
#### Adjust the background color used for `resize_and_pad`
|
||||
|
||||
Vips uses black as the default background color `resize_and_pad`, instead of white like ImageMagick. Fix that by using the `background` option:
|
||||
|
||||
```diff
|
||||
@ -576,6 +579,7 @@ Vips uses black as the default background color `resize_and_pad`, instead of whi
|
||||
```
|
||||
|
||||
#### Remove any EXIF based rotation
|
||||
|
||||
Vips will auto rotate images using the EXIF value when processing variants. If you were storing rotation values from user uploaded photos to apply rotation with ImageMagick, you must stop doing that:
|
||||
|
||||
```diff
|
||||
@ -584,6 +588,7 @@ Vips will auto rotate images using the EXIF value when processing variants. If y
|
||||
```
|
||||
|
||||
#### Replace monochrome with colourspace
|
||||
|
||||
Vips uses a different option to make monochrome images:
|
||||
|
||||
```diff
|
||||
@ -592,6 +597,7 @@ Vips uses a different option to make monochrome images:
|
||||
```
|
||||
|
||||
#### Switch to libvips options for compressing images
|
||||
|
||||
JPEG
|
||||
|
||||
```diff
|
||||
@ -621,6 +627,7 @@ GIF
|
||||
```
|
||||
|
||||
#### Deploy to production
|
||||
|
||||
Active Storage encodes into the url for the image the list of transformations that must be performed.
|
||||
If your app is caching these urls, your images will break after you deploy the new code to production.
|
||||
Because of this you must manually invalidate your affected cache keys.
|
||||
|
@ -133,10 +133,7 @@ that you should choose a traditional bundler include:
|
||||
[Webpack loaders](https://webpack.js.org/loaders/).
|
||||
* If you are absolutely sure that you need
|
||||
[tree-shaking](https://webpack.js.org/guides/tree-shaking/).
|
||||
* If you will install Bootstrap, Bulma, PostCSS, or Dart CSS through the
|
||||
[cssbundling-rails gem](https://github.com/rails/cssbundling-rails). All options provided by this
|
||||
gem except Tailwind and Sass will automatically install `esbuild` for you if you do not specify a different
|
||||
option in `rails new`.
|
||||
* If you will install Bootstrap, Bulma, PostCSS, or Dart CSS through the [cssbundling-rails gem](https://github.com/rails/cssbundling-rails). All options provided by this gem except Tailwind and Sass will automatically install `esbuild` for you if you do not specify a different option in `rails new`.
|
||||
|
||||
Turbo
|
||||
-----
|
||||
|
Loading…
Reference in New Issue
Block a user