Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Add Contributing section
Damian Legawiec953ff82599d7
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.mdindex b3899b06b3..e0bbd3fee2 100644--- a/.github/CONTRIBUTING.md+++ b/.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!diff --git a/guides/src/content/developer/7_contributing/developing_spree.md b/guides/src/content/developer/7_contributing/developing_spree.mdnew file mode 100644index 0000000000..0b632d644f--- /dev/null+++ b/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!diff --git a/guides/src/content/developer/tutorials/extensions_tutorial.md b/guides/src/content/developer/7_contributing/extensions_tutorial.mdsimilarity index 99%rename from guides/src/content/developer/tutorials/extensions_tutorial.mdrename to guides/src/content/developer/7_contributing/extensions_tutorial.mdindex 64ec53c4ad..a6711edc53 100644--- a/guides/src/content/developer/tutorials/extensions_tutorial.md+++ b/guides/src/content/developer/7_contributing/extensions_tutorial.md@@ -1,6 +1,7 @@---title: Creating an Extension-section: tutorial+section: contributing+order: 1---## Getting Starteddiff --git a/guides/src/content/developer/7_contributing/index.md b/guides/src/content/developer/7_contributing/index.mdnew file mode 100644index 0000000000..d93ef1a78d--- /dev/null+++ b/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.diff --git a/guides/src/content/developer/tutorials/upgrading_extensions.md b/guides/src/content/developer/7_contributing/upgrading_extensions.mdsimilarity index 73%rename from guides/src/content/developer/tutorials/upgrading_extensions.mdrename to guides/src/content/developer/7_contributing/upgrading_extensions.mdindex a569d6cf11..1d345cd104 100644--- a/guides/src/content/developer/tutorials/upgrading_extensions.md+++ b/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 doend```-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 configurationYou can always find up-to-date Travis CI config here: https://github.com/spree/spree/blob/master/cmd/lib/spree_cmd/templates/extension/travis.ymlFor 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 configYou can always find up-to-date Appraisals config here: https://github.com/spree/spree/blob/master/cmd/lib/spree_cmd/templates/extension/AppraisalsFor 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 OverridesSome 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 tAlso - **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 ToolsReplace 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)-```diff --git a/guides/src/content/developer/tutorials/developing_spree.md b/guides/src/content/developer/tutorials/developing_spree.mddeleted file mode 100644index 7e805ac1cf..0000000000--- a/guides/src/content/developer/tutorials/developing_spree.md+++ /dev/null@@ -1,134 +0,0 @@-----title: Developing Spree-section: tutorial-order: 2------## Overview--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.--## Setup locally--Clone the Git repo--```shell-git clone git://github.com/spree/spree.git-cd spree-```--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, please [install homebew](https://brew.sh/). With homebrew installed you will need to install some packages needed to run Spree and Rails applications in general:--```bash-brew install openssl mysql postgresql sqlite imagemagick-```--## Sandbox--Create a sandbox Rails application for testing purposes which automatically performs all necessary database setup--```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-```--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.--## 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-```