Add Contributing section

.github/CONTRIBUTING.md

@@ -1,62 +1 @@
-## Pull requests
-
-We gladly accept pull requests to add new features, bug fixes, documentation updated and overall any improvements to the codebase! All contributions (even the smallest ones) are welcome!
-
-Here's a quick guide:
-
-1. Fork the repo
-
-2. Clone the fork to your local machine
-
-3. Run `bundle install` inside `spree` directory
-
-4. Create a sandbox environment
-
-  ```bash
-  bundle exec rake sandbox
-  ```
-
-5. To run a sandbox application:
-
-  ```bash
-  cd sandbox
-  bundle exec rails s
-  ```
-
-6. Create new branch then make changes and add tests for your changes. Only
-refactoring and documentation changes require no new tests. If you are adding
-functionality or fixing a bug, we need tests!
-
-7. Run the tests. [See instructions](https://guides.spreecommerce.org/developer/tutorials/developing_spree.html#running-tests)
-
-8. Push to your fork and submit a pull request. If the changes will apply cleanly
-to the master branch, you will only need to submit one pull request.
-
-  Don't do pull requests against `-stable` branches. Always target the master branch. Any bugfixes we'll backport to those branches.
-
-At this point, you're waiting on us. We like to at least comment on, if not
-accept, pull requests within three business days (and, typically, one business
-day). We may suggest some changes or improvements or alternatives.
-
-Some things that will increase the chance that your pull request is accepted,
-taken straight from the Ruby on Rails guide:
-
-* Use Rails idioms and helpers
-* Include tests that fail without your code, and pass with it
-* Update the documentation, the surrounding one, examples elsewhere, guides,
-  whatever is affected by your contribution
-
-Syntax:
-
-* Two spaces, no tabs.
-* No trailing whitespace. Blank lines should not have any space.
-* Use &&/|| over and/or.
-* `MyClass.my_method(my_arg)` not `my_method( my_arg )` or `my_method my_arg`.
-* `a = b` and not `a=b`.
-* `a_method { |block| ... }` and not `a_method { | block | ... }`
-* Follow the conventions you see used in the source already.
-* Use -> symbol for **inline** lambdas and lambda method for **multiline** lambdas
-* Ruby 1.9 hash syntax `{ key: value }` over Ruby 1.8 hash syntax `{ :key => value }`
-* Alphabetize the class methods to keep them organized
-
-And in case we didn't emphasize it enough: we love tests!
+Please visit [Contributing section](http://guides.spreecommerce.org/developer/contributing/) of Spree Guides. Thank you!

guides/src/content/developer/7_contributing/developing_spree.md

@@ -0,0 +1,174 @@
+---
+title: Developing Spree
+section: contributing
+order: 0
+---
+
+## Overview
+
+This guide covers all the necessary steps to contributing to Spree source code. We're happy you're here!
+
+## Fork Spree repo
+
+Go to [Spree GitHub repository](https://github.com/spree/spree) and click **Fork** button. This will create a copy of Spree repository on your GitHub account. See [Github Documentation](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) for more information on forking.
+
+## Setup locally
+
+1. Clone the your fork repository
+
+    ```shell
+    git clone git://github.com/your_github_username/spree.git
+    cd spree
+    ```
+
+2. Install the gem dependencies
+
+    ```shell
+    bundle install
+    ```
+
+### Fix Bundle errors on MacOS
+
+If `bundle install` fails that means you're missing some required system libraries.
+
+Firstly, ensure you hve [homebrew installed](https://brew.sh/). You will need to install some packages needed to run Spree and Rails applications in general:
+
+```shell
+brew install openssl mysql postgresql sqlite imagemagick
+```
+
+## Create Sandbox application
+
+Spree is meant to be run within the context of Rails application and the source code is essentially a collection of gems. You can easily create a sandbox application inside of your cloned source directory for testing purposes.
+
+This will setup a Rails application with Spree and some essential extensions and gems pre-installed with some data seeded Sandbox application is not meant to be run on production!
+
+```shell
+bundle exec rake sandbox
+```
+
+For **headless sandbox** please run:
+
+```shell
+SPREE_HEADLESS=true bundle exec rake sandbox
+```
+
+By default Sandbox uses **SQLite** database. But you can switch to **PostgreSQL**:
+
+```shell
+DB=postgres bundle exec rake sandbox
+```
+
+or **MySQL**:
+
+```shell
+DB=mysql bundle exec rake sandbox
+```
+
+You can also combine those options:
+
+```shell
+SPREE_HEADLESS=true DB=postgres bundle exec rake sandbox
+```
+
+Start the server
+
+```shell
+cd sandbox
+bundle exec rails s
+```
+
+### Performance in development mode
+
+You may notice that your Spree store runs slower in development environment. This can be because in development each asset (css and javascript) is loaded separately. You can disable it by adding the following line to `config/environments/development.rb`.
+
+```ruby
+config.assets.debug = false
+```
+
+### Caching
+
+Also in development caching is disabled by default. To turn on caching run:
+
+```bash
+bundle exec rails dev:cache
+```
+
+You will need to restart rails server after this change.
+
+## Making changes
+
+Create a new branch for your changes. Do not push changes to the main branch. Branch name should be human readable and informative, eg.
+
+* bug fixes: `fix/order-recalculation-total-bug`
+* features: `feature/my-new-amazing-feature`
+
+## Running Tests
+
+We use [CircleCI](https://circleci.com/) to run the tests for Spree.
+
+You can see the build statuses at [https://circleci.com/gh/spree/spree](https://circleci.com/gh/spree/spree).
+
+Each gem contains its own series of tests, and for each directory, you need to
+do a quick one-time creation of a test application and then you can use it to run
+the tests.  For example, to run the tests for the core project.
+
+```shell
+cd core
+BUNDLE_GEMFILE=../Gemfile bundle exec rake test_app
+bundle exec rspec spec
+```
+
+If you would like to run specs against a particular database you may specify the
+dummy app's database, which defaults to sqlite3.
+
+```shell
+DB=postgres BUNDLE_GEMFILE=../Gemfile bundle exec rake test_app
+```
+
+If you want to run specs for only a single spec file
+
+```shell
+cd core
+bundle exec rspec spec/models/spree/state_spec.rb
+```
+
+If you want to run a particular line of spec
+
+```shell
+cd core
+bundle exec rspec spec/models/spree/state_spec.rb:7
+```
+
+### Running integration tests on MacOS
+
+We use chromedriver to run integration tests. To install it please use this command:
+
+```bash
+brew cask install chromedriver
+```
+
+## Submitting Changes
+
+Please keep your commit history meaningful and clear. [This guide](https://about.gitlab.com/blog/2018/06/07/keeping-git-commit-history-clean/) covers it quite well and we recommend reading it, not only for Spree project but for any IT project overall.
+
+1. Push your changes to a topic branch in your fork of the repository.
+
+    ```shell
+    git push -u origin fix/order-recalculation-total-bug
+    ```
+
+2. Create a Pull request - [please follow this guide](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork)
+
+    If your changes references Github issues, please mark which issue you're fixing by adding `Fixes #<number or url of the issue>` in the commit name or PR title/description.
+    This will automatically mark that issue as closed when your PR will be merged.
+
+3. Wait for CI to pass
+
+4. If CI passed wait for Spree Core team code review
+
+    We're aiming to review and leave feedback as soon as possible. We'll leave you a meaningul feedback if needed.
+
+## That's a wrap!
+
+Thank you for participating in Open Source and improving Spree - you're awesome!

guides/src/content/developer/tutorials/extensions_tutorial.md → guides/src/content/developer/7_contributing/extensions_tutorial.md

@@ -1,6 +1,7 @@
 ---
 title: Creating an Extension
-section: tutorial
+section: contributing
+order: 1
 ---
 
 ## Getting Started

guides/src/content/developer/7_contributing/index.md

@@ -0,0 +1,36 @@
+---
+title: "Contributing"
+section: contributing
+---
+
+Spree is an open, community powered project that anyone can contribute to. There are several ways you can help us improve Spree:
+
+* submitting an issue describing a bug or a feature request
+* fixing a bug or creating a new feature
+* creating a Spree extension
+* upgrading old extensions to recent Spree versions
+* helping others on Spree slack
+
+## Submitting issues
+
+You can [submit an issue](https://github.com/spree/spree/issues/new/choose) on our [Github Issues tracker](https://github.com/spree/spree/issues)
+
+## Fixing a bug or creating a new feature
+
+Before diving into the Spree codebase we recommend you spend some time to review the [Internals section](/developer/internals/) which will help you understand how Spree works under the hood.
+
+After you're done with that please follow to [Developing Spree guide](/developer/contributing/developing_spree.html)
+
+To find issues you can tackle on we recommend visiting [Spree Contribute page](https://github.com/spree/spree/contribute) which lists issues tagged with [Good First Issue label](https://github.com/spree/spree/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22). Those bugs or features are great starting points into Open Source development.
+
+## Creating a Spree extension
+
+Extensions provide additional features and integrations for your Spree store. You can create your own and share with the rest of the community. Before doing so please check our [Extension directory](/extensions) if your desired extension does not exist already. If not [follow Extensions tutorial](/developer/contributing/extensions_tutorial.md) to learn how to create one.
+
+## Upgrading old extensions to recent Spree versions
+
+If you found an extension that does not work with the current Spree version you can read the [Updating Extensions for Spree guide](/developer/contributing/upgrading_extensions.html) to bring it up to speed.
+
+## Helping others on Spree slack
+
+Last but not least, you're invited to [join our slack](http://slack.spreecommerce.org) to help and receive guidance from fellow Spree developers including Spree Core Team.

guides/src/content/developer/tutorials/upgrading_extensions.md → guides/src/content/developer/7_contributing/upgrading_extensions.md

@@ -1,19 +1,22 @@
 ---
-title: Updating Extensions to Rails 6 and Spree 4
-section: advanced
+title: Updating Extensions for Spree 4
+section: contributing
+order: 2
 ---
 
-### Zeitwerk compatibility
+## Overview
 
-Zeitwerk is a new default code autoloader in Rails 6. See https://weblog.rubyonrails.org/2019/2/22/zeitwerk-integration-in-rails-6-beta-2/
+This guide covers the process of migrating an old Spree 2/3 extension to Spree 4.
 
-This doesn't work well with the old approach to decorators (files that name ends with decorator.rb, eg. `app/models/spree/order_decorator.rb`) in Spree using `class_eval` (we should always use `Module.prepend`, [more on this](https://medium.com/@leo_hetsch/ruby-modules-include-vs-prepend-vs-extend-f09837a5b073)).
+## Zeitwerk compatibility
 
-To fix this we need to convert all class_eval decorators to Module.prepend and name them properly according to Zeitwerk rules: https://github.com/fxn/zeitwerk#file-structure
+Zeitwerk is the [new default code autoloader in Rails 6](https://weblog.rubyonrails.org/2019/2/22/zeitwerk-integration-in-rails-6-beta-2/).
 
-Eg.
+This doesn't work well with the old approach to decorators (files that name ends with decorator.rb, eg. `app/models/spree/order_decorator.rb`) using [class_eval](https://www.jimmycuadra.com/posts/metaprogramming-ruby-class-eval-and-instance-eval/).
 
-old decorator
+To fix this we need to convert all `class_eval` decorators to modules and use [Module.prepend](https://medium.com/@leo_hetsch/ruby-modules-include-vs-prepend-vs-extend-f09837a5b073). Also we need to name them properly according to [Zeitwerk naming rules](https://github.com/fxn/zeitwerk#file-structure)
+
+Example of an old decorator:
 
 `app/models/spree/order_decorator.rb`
 ```ruby
@@ -26,7 +29,7 @@ Spree::Order.class_eval do
 end
 ```
 
-new one:
+the same decorator in the new notation:
 
 `app/models/your_extension_name/order_decorator.rb`
 ```ruby
@@ -43,11 +46,11 @@ end
 ::Spree::Order.prepend(YourExtensionName::OrderDecorator)
 ```
 
-###  Travis CI configuration
+## Travis CI configuration
 You can always find up-to-date Travis CI config here: https://github.com/spree/spree/blob/master/cmd/lib/spree_cmd/templates/extension/travis.yml
 For the rationale of the changes please look at the blame view: https://github.com/spree/spree/blame/master/cmd/lib/spree_cmd/templates/extension/travis.yml
 
-### Appraisals config
+## Appraisals config
 You can always find up-to-date Appraisals config here: https://github.com/spree/spree/blob/master/cmd/lib/spree_cmd/templates/extension/Appraisals
 
 For the rationale of the changes please look at the blame view: https://github.com/spree/spree/blame/master/cmd/lib/spree_cmd/templates/extension/Appraisals
@@ -58,7 +61,7 @@ After each change please remember to re-generate gemfiles by running:
 bundle exec appraisal generate --travis
 ```
 
-### Fixing Deface Overrides
+## Fixing Deface Overrides
 Some Extensions still use Deface overrides to add some UI features, mainly in the admin panel. Deface isn't recommended. If you can use other methods.
 Eg. If your extension adds a link to the Admin Panel menu you can do it this way https://guides.spreecommerce.org/developer/customization/view.html#adding-new-links-to-the-admin-panel-menu
 
@@ -69,7 +72,7 @@ Spree 4 uses Bootstrap 4 and many partials and HTML structure changed compared t
 
 Also - **remember to add deface gem to gemspec** as deface itself was removed as a dependency of Spree. eg. https://github.com/spree/spree_auth_devise/commit/d729689ca87d8586e541ffcc865ef1e0a5a79fe4
 
-### Migrate to Spree Dev Tools
+## Migrate to Spree Dev Tools
 Replace all development dependencies with:
 
 ```ruby
@@ -85,10 +88,3 @@ Example migrations:
 * https://github.com/spree/spree_gateway/pull/357
 * https://github.com/spree-contrib/spree-product-assembly/pull/200
 * https://github.com/spree/spree_auth_devise/pull/487
-
-### Fixing deprecations
-Please fix any Rails 6.1 deprecations eg.
-
-```ruby
-DEPRECATION WARNING: update_attributes! is deprecated and will be removed from Rails 6.1 (please, use update! instead)
-```