MaMpf (Mathematical Media Platform) β an E-Learning platform for mathematics featuring a media player & editor. Developed & deployed at Heidelberg University.
Currently, there are different setups on different machines and everyone styles the code to their liking. Why not have a common standard to ease reading the code? This issue paints a roadmap to achieve this goal.
Note: maybe we can get inspired regarding linter recommendations from the Ruby forum here. I've also asked here.
If you're unfamiliar with what autoformatting, linting and the like means, see this blog post on GitHub. It has some great examples.
VSCode
In VSCode one can share recommended extensions as well as workplace settings, e.g. see here. To do so, we'd have to commit the .vscode folder to our repo.
Status: Not implemented yet. Should probably wait until we've settled on extensions we really want to use.
Lint Ruby files (.rb)
We use RuboCop to lint .rb files. The VSCode plugin Ruby LSP by shopify allows you to automatically run RuboCop with our ruleset in the background and autoformat the .rb file you're working with. This makes it super easy to comply with our coding standards.
Status: #564 will redo the RuboCop to have some sensible defaults. #562 will bring a check to our CI/CD to enforce the style guide. TODO: add Ruby LSP extensions to recommended extensions. Theoretically speaking, this is a solved problem. β
Lint Ruby code inside .erb files
In Shopify's ERB Lint, one can activate RuboCop which "runs RuboCop rules on ruby statements found in ERB templates". This is exactly what we want. I haven't tried it out yet. It also offers many different linting corrections for erb files generally. Maybe we can also just use the Rubocop part in there and deactivate all other things if we found more specific linters for HTML/JS? We also have to be able to run it from the command line in order to integrate it into our CI/CD pipeline.
Status: Shopify ERB lint might work. Will have to try things out.
Lint HTML files (.html & .html.erb)
For the ERB part, htmlbeautifier might be an option. However, we also want to lint plain .html files, so we should find a solution that works for both. vscode-html-erb might also be an option, but it is also just for the HTML part in .html.erb files. And I don't know if one can invoke it via the command line as well (which we need for CI/CD integration).
Status: No mature ideas yet. Should find a solution such that we can have one ruleset for all .html stuff (and not one for .html and another for .html.erb).
Lint JS files (.js & .js.erb)
ESLint is a very popular "tool for identifying and reporting on patterns found in ECMAScript/JavaScript code." I've already used it in some of my JS projects and it just works. At least for plain .js files.
For .js.erb files, one would have to write a small processor to strip the <% ... Ruby parts such that ESLint can work with the files. This is already done here. However, the repo is abandoned and we have to watch out with the license. But it doesn't seem like a big task to write this small plugin on your own. Still, I'm not sure how to deal with source maps as described here.
Edit: It was a huge task π But I managed to write my own plugin to lint the JavaScript parts of the .js.erb files. Will have to see if everything works as expected in the wild ;)
Prettier also offers prettier-eslint which combines Prettier with ESLint. I'm not sure though if one can then still configure ESLint to have the custom processor applied in order to work with .js.erb files.
Status: Ideas begin to form, more experimentation needed. I've written a custom plugin to do this task π Will have to integrate it with MaMpf.
Lint CSS files
Status: Haven't looked into that yet, but shouldn't be a big problem as there are just plain .css files and I bet there's tons of available linters out there for CSS.
Lint Coffee files
Don't lint them, instead get rid of Coffeescript altogether and replace by .js files.
Further ideas / notes
Prettifier is very popular to lint all kinds of languages, but we have to keep in mind it's opinionated and alongside that not configurable (which might actually be a good thing). There are many Plugins for different languages, even an official plugin for Ruby, but we don't need that as RuboCop is working really fine with the Ruby LSP VSCode extension.
For Prettifier, there's also a plugin to lint erb files, however we shouldn't use it as it seems abandoned (see this issue, and the linked issue there).
To also store useful commands for the command line, we could use Just, it's super easy and I've made some very, very positive experiences with it.
Currently, there are different setups on different machines and everyone styles the code to their liking. Why not have a common standard to ease reading the code? This issue paints a roadmap to achieve this goal.
Note: maybe we can get inspired regarding linter recommendations from the Ruby forum here. I've also asked here.
If you're unfamiliar with what autoformatting, linting and the like means, see this blog post on GitHub. It has some great examples.
VSCode
In VSCode one can share recommended extensions as well as workplace settings, e.g. see here. To do so, we'd have to commit the
.vscode
folder to our repo.Status: Not implemented yet. Should probably wait until we've settled on extensions we really want to use.
Lint Ruby files (
.rb
)We use
RuboCop
to lint.rb
files. The VSCode pluginRuby LSP by shopify
allows you to automatically run RuboCop with our ruleset in the background and autoformat the.rb
file you're working with. This makes it super easy to comply with our coding standards.Status: #564 will redo the RuboCop to have some sensible defaults. #562 will bring a check to our CI/CD to enforce the style guide. TODO: add
Ruby LSP
extensions to recommended extensions. Theoretically speaking, this is a solved problem. βLint Ruby code inside
.erb
filesIn Shopify's
ERB Lint
, one can activateRuboCop
which "runs RuboCop rules on ruby statements found in ERB templates". This is exactly what we want. I haven't tried it out yet. It also offers many different linting corrections for erb files generally. Maybe we can also just use the Rubocop part in there and deactivate all other things if we found more specific linters for HTML/JS? We also have to be able to run it from the command line in order to integrate it into our CI/CD pipeline.Status: Shopify ERB lint might work. Will have to try things out.
Lint HTML files (
.html
&.html.erb
)For the ERB part, htmlbeautifier might be an option. However, we also want to lint plain
.html
files, so we should find a solution that works for both.vscode-html-erb
might also be an option, but it is also just for the HTML part in.html.erb
files. And I don't know if one can invoke it via the command line as well (which we need for CI/CD integration).Status: No mature ideas yet. Should find a solution such that we can have one ruleset for all
.html
stuff (and not one for.html
and another for.html.erb
).Lint JS files (
.js
&.js.erb
)ESLint
is a very popular "tool for identifying and reporting on patterns found in ECMAScript/JavaScript code." I've already used it in some of my JS projects and it just works. At least for plain.js
files.For
.js.erb
files, one would have to write a small processor to strip the<% ...
Ruby parts such that ESLint can work with the files. This is already done here. However, the repo is abandoned and we have to watch out with the license.But it doesn't seem like a big task to write this small plugin on your own. Still, I'm not sure how to deal with source maps as described here.Edit: It was a huge task π But I managed to write my own plugin to lint the JavaScript parts of the
.js.erb
files. Will have to see if everything works as expected in the wild ;)Prettier also offers prettier-eslint which combines Prettier with ESLint. I'm not sure though if one can then still configure ESLint to have the custom processor applied in order to work with
.js.erb
files.Status:
Ideas begin to form, more experimentation needed.I've written a custom plugin to do this task π Will have to integrate it with MaMpf.Lint CSS files
Status: Haven't looked into that yet, but shouldn't be a big problem as there are just plain
.css
files and I bet there's tons of available linters out there for CSS.Lint Coffee files
Don't lint them, instead get rid of Coffeescript altogether and replace by
.js
files.Further ideas / notes
Ruby LSP
VSCode extension.Just
, it's super easy and I've made some very, very positive experiences with it.