Intro
This document is meant to highlight best practices for contributing to the general PixelOven project. If you are looking for specifics on how to setup this project for development of apps or packages please review the quick start guide. Otherwise for ideas on how to go about working within our best practices please review our recommendation section.
Requirements
These steps will guide you through contributing to this project:
- Ensure Node >=
10.0.0and yarn >=1.0.0 - Ensure yarn is installed
- Clone repository and install dependencies
Note please ensure system has these minimum requirements or greater.
Manually checking requirements
Check "engine" requirements:
Please follow these official instructions to install yarn for your specific system.
Please follow these official instructions to install lerna globally.
Recommended Development Approach
Note it is recommended to periodically re-install deps to ensure latest version during development.
When developing component(s) the recommended development workflow is as follows.
- Build component in isolation using StoryBook
- Write/Modify co-located unit tests for component(s).
- Integrate component into application
- Write/Modify integration tests that might utilize component(s).
- Finally spin up docker to verify application with back-end services.
Using shortcuts
The main project contains a few shortcuts for working with all packages. These scripts are helpful when making sweeping changes or testing the entire project but generally are not meant for an iterative workflow.
In the root project directory run the following to compile packages.
Once compiled sym-links will need to be updated.
For code quality checks and formatting the following scripts can be run.
Other variations of these scripts exist. Generally speaking all packages will follow a very similar pattern but it is possible that specialty packages may have other requirements.
Using Lerna
For the examples below
{NAME}refers to the value found in each packagespackage.jsonunder the keyname.
When working with a specific package we can use Lerna to help us manage our workflow and reduce the need from change directories often.
From anywhere within the project you can compile a specific package with the following cmd.
Once compiled sym-links will need to be updated.
For code quality checks and formatting the following scripts can be run.
Once again other variations of these scripts may exist. Please review the package.json in the root of this project for shortcuts.
It is highly encourage to read this documentation for an in-depth look at how to work with lerna.
Committing
Note commit formatting is helpful for us for generating a CHANGELOG so we know what goes into each tagged release. The actual version doesn't matter as much as tracking our changes in a highly discoverable way.
Commit Linting
When executing a standard commit git commit the pre-commit hook will check the format of the message -m.
Invalid commit might look like:
versus a valid commit:
Currently the linter will accept either of the above formats however knowing what starting tag to use may be more difficult. To facilitate this we can run an interactive console.
Commit Console
Note this console is meant to guide your commits but is not necessary to commit code.
To start you will be presented with a menu of commit tag types.
A few more options will be presented to help guide your commit.
Pull Requests
Keep in mind that this project is a mono-repo design. If you encounter any issue when running scripts it is recommended to run yarn clean at the root of this project and re run the setup above.
Make both your branches and commits descriptive. Ensure "lerna" commands such as lerna run build and lerna run test work properly before submitting a pull request.
Finally send a GitHub Pull Request with a clear list of what you've done (read more about pull requests). Make sure all of your commits are atomic (one feature per commit).