Getting started documentation #2433
Conversation
I rewrote the getting started guide to focus on first-time installations. Other "getting started"-related information can reside in this subdirectory alongside this article. The article is opinionated in that it focuses on macOS users. The rationale for this is that a) Linux users are more likely to know how to install the required system dependencies and don't need that hand-holding and b) Windows users have to jump through additional hoops to get Solidus up and running (we don't recommend this). That said, there are still links and resources for Linux users available in this article.
Much of this content is borrowed from Solidus's README.md.
| all incoming pull requests. | ||
|
|
||
| To run the test suites for `solidus_frontend` and `solidus_backend`, you need to | ||
| install [PhantomJS](http:https://phantomjs.org/) on your system first. |
There was a problem hiding this comment.
We don't use phantoms anymore.
You need to install chromedriver on your system first.
There was a problem hiding this comment.
Thank you. I will also update this in the README.
| DB=mysql bash build.sh | ||
| ``` | ||
|
|
||
| Note that this will fail if you have not installed PhantomJS on your system. |
| You can enable `FAIL_FAST` to stop any test run after the first failure: | ||
|
|
||
| ```shell | ||
| FAIL_FAST=true bundle exec rspec spec/models/state_spec.rb |
There was a problem hiding this comment.
We should not promote a custom ENV var, but the rspec --fail-fast feature instead. But this is common rspec knowledge, I don't think we need to mention it in our guides at all.
There was a problem hiding this comment.
I actually took this from the README:
You can also enable fail fast in order to stop tests at the first failure
FAIL_FAST=true bundle exec rspec spec/models/state_spec.rb
Would you 👍 my removing this from the README as well?
I would agree that we should remove this if it's common rspec knowledge. Instead I'll just explicitly state to reference the rspec documentation for testing needs.
| @@ -0,0 +1,94 @@ | |||
| # Installation options | |||
|
|
|||
| ## Bleeding edge Solidus | |||
There was a problem hiding this comment.
This headline belongs to the next paragraph and this headline should be something like
Stable Solidus
| Solidus uses [RSpec](http:https://rspec.info/) for testing. | ||
|
|
||
| If you intend to submit your work to Solidus as a pull request, it must pass all | ||
| of the Solidus test suites before it is merged. We use CircleCI to run tests on |
There was a problem hiding this comment.
and you need to provide tests for your bug fix or new feature as well.
benjaminwil
force-pushed
the
getting_started_documentation
branch
from
940089a
to
5a11c63
Compare
|
@tvdeyen Thanks for the review. All of the issues are fixed. |
benjaminwil
force-pushed
the
getting_started_documentation
branch
from
5a11c63
to
9eeb1af
Compare
In solidusio#2433, I rewrote and expanded the getting started guide to discuss developing Solidus. In a review, tvdeyen requested some changes regarding testing. These changes are also required in Solidus's README: - Solidus no longer uses PhantomJS for running backend and frontend tests. Now it uses ChromeDriver. - tvdeyen also mentioned "We should not promote a custom ENV var [`FAIL_FAST=true`] but the rspec `--fail-fast` feature instead. But this is common rspec knowledge, I don't think we need to mention it in our guides at all." I also took the liberty of making the markdown more readable in this section.
Thanks to tydeyen for his review of my pull request. I've updated the information about testing and Solidus development to be more accurate.
benjaminwil
force-pushed
the
getting_started_documentation
branch
from
9eeb1af
to
3022675
Compare
I rewrote the getting started documentation to focus on first-time installations. Other "getting started"-related information can reside in this subdirectory alongside this article.
The article is opinionated in that it focuses on macOS users. The rationale for this is that a) Linux users are more likely to know how to install the required system dependencies and don't need that hand-holding. We also don't shell commands for every package manager out there. b) Windows users have to jump through additional hoops to get Solidus up and running. (We don't officially support or recommend using Windows right now.)
I split out information about common installation options and developing Solidus into separate articles so that they can blossom into their own full-fledged guides. Much of the information in them right now is borrowed from the README.md.
This is part a larger project to improve Solidus's documentation. See this gist with the high-level table of contents. Where and how this documentation will exist is still up for discussion.