Venia Code Requirements

Venia Code Requirements

Congratulations! You're contributing to the codebase of the Venia storefront concept, which is a very special codebase. We've committed ourselves to holding Venia code to an exceptionally high standard. Our authors and volunteer contributors have held to this standard, and we believe anyone can. There isn't a lot to remember, and there are no small or arbitrary rules here. On this project, we don't waste time debating semicolons.

Code Purpose

Venia code must serve all these purposes, and your contribution should honor those purposes:

Solve a problem

All code changes must make Venia a better eCommerce site and a better PWA in a measurable way. An eCommerce site must have a number of complex, yet user-friendly workflows. Progressive Web Apps serve a number of difficult use cases and conditions. An eCommerce PWA therefore has a lot of problems to solve. A PR should solve a problem that Venia experiences today; we can anticipate future problems that emerge, but we have to solve current problems before we admit code changes that only pertain to future scaling or architectural concerns.

Follow the Magento Commerce 2 feature set

Venia is a showcase of the new Magento 2 storefront experience. Each component, action, and module should help to express a Magento 2 feature. Venia should ultimately support all Magento 2 core storefront functionality, including bundled extensions. PRs which implement any functionality which Magento already exposes in its GraphQL or REST APIs should use those APIs.

Be a teaching tool

As a contributor to Venia, you're writing code that a big community of partners and developers will read, to learn how PWA Studio and Magento PWAs work. Code should be readable; we keep to this rule with code review and case-by-case opinion, rather than with excessive code linting or rules about comments.

Code Quality

Venia must be high-quality code. It must run reliably in all supported environments, it must be consistent in style, it must be as easy as possible to refactor, and it must covered by tests. To keep our code quality high, your contribution should:

Run in supported browsers

In our Definition of Quality, we define which browsers Venia must support. Any code changes must work reliably in all of these browsers, or fall back to an acceptable graceful degradation experience.

Adhere to the style of the project

Don't worry about semicolons, carriage returns, or underscores. In our definition, the "style" of the project is the overall architecture of PWA Studio as described in our core documentation. Some general rules to follow include, but are not limited to:

• For contributions to the current release branch, use only Magento features in the current release candidate or version (currently Magento 2.3.0).
• Whenever possible, use the Magento GraphQL API to obtain data. The Magento REST API is currently in use for those areas GraphQL does not cover in 2.3.0, but it is considered to be temporary; the project's goal is to use only GraphQL for data.
• Whenever possible, use the Apollo <Query /> component to call the Magento GraphQL API. Other GraphQL call styles will be evaluated case-by-case.
• When using the REST API, use the @magento/peregrine/RestAPI client directly, with no intermediate abstractions. Uses of the REST API should be considered semi-deprecated, so we should not introduce any public module API in JavaScript which depends on the REST API.
• All client-side changes to be shared between components should be dispatched as Redux Actions and handled by Redux reducers. Use react-redux bindings to subscribe individual components to these changes.
• Reducers and actions are grouped by features, such as cart, user, and order. Any reducer can handle any action in any namespace, but it should only modify its subsection of store state. Action creators should only dispatch actions in their own namespace.
• Always use CSS Modules for styling components. Always use the classify higher-order component to export the generated CSS classes on components.

Here are some examples of Venia code contributions that would violate project style:

• Statically importing large libraries
• Using DOM nodes directly where React elements would work
• Writing style outside of the CSS Modules system
• Writing style that does not resemble the rest of the style in the project, e.g.:
  • Writing complex selectors instead of plain class selectors
  • Hardcoding common instead of using CSS Variables
  • Using arbitrary pixel widths instead of rem and fr
  • Using "CSS hacks" for older browsers
• Causing side effects at module load time (except in src/index.js)
• Adding stateful shared globals anywhere but in the Redux store (including parent component state)
• Adding server-side code to Venia outside the UPWARD file and template files

As the project matures, this definition will update to be more detailed, instead of a list of "do's and don'ts". In the meantime, code reviewers should be vigilant in maintaining the essential structure of the Venia project.

Make it easy to refactor

If your functionality can be a React component, make it a React component. React components have a simple, consistent API. If your functionality changes state, create a Redux action creator and reducer. If your functionality is shared by many components, consider writing a React component instead of a general-purpose utility.

And finally, if your code is more generally useful to PWAs, and is not specific to Venia UX or Magento workflow, consider adding it to Peregrine!

Write tests

We test with Jest. We test React components with Enzyme. Code contributions should include tests. New code should be 100% covered, or if not 100% covered, should include comments to disable Istanbul coverage and explain why the test cannot reach this branch of code.