Skip to content

Latest commit

 

History

History
195 lines (125 loc) · 6.46 KB

CONTRIBUTING.md

File metadata and controls

195 lines (125 loc) · 6.46 KB

Contributing to Force

This project is work of many developers.

We accept pull requests, and you may propose features and discuss issues.

In the examples below, substitute your GitHub username for contributor in URLs.

Fork the Project

Fork the project on GitHub and check out your copy.

git clone https://github.com/contributor/force.git
cd force
git remote add upstream https://github.com/artsy/force.git

Run Force

Install NVM and Node 10.

nvm install 10
nvm alias default 10

Install node modules with Yarn.

npm i yarn -g
yarn install

Copy the .env.oss file to a .env file.

cp .env.oss .env

Start the server.

yarn start

Force should now be running at http://localhost:5000/.

Real-time development with Reaction

When working with components built in Reaction and want to keep both environments in sync without publishing to NPM, run:

cd reaction
yarn link && yarn watch

# Open a new terminal pane
cd force
yarn link @artsy/reaction && yarn start

Running a local copy of Force in Production mode:

yarn start:prod

This creates a production-ready bundle of client and server-side code and boots the server. (This will take a while to compile.)

In case you want to ease debugging the server-side code, you can set the DEBUG environment variable to disable webpack optimizations.

env DEBUG=true yarn start:prod

Creating a Review App

If wanting to create a deploy for a WIP feature or for QA, Hokusai, supports Review Apps.

The process for launching the review app differs somewhat depending on whether your unmerged changes are in Reaction or in Force.

If your unmerged changes are in Reaction

You will first cut a release of Reaction and publish it as a "canary" version to the NPM registry. You will then install this canary release into your copy of Force and launch that as review app.

  1. Login to the NPM registry with npm login. (You will need to already have an NPM account, and it will need to be associated with the Artsy NPM org — holler on #front-end if you need help with this.)

  2. Update reaction/package.json to have a canary version number, e.g. 22.9.8-canary-<your PR number>

  3. Publish the package under the canary tag with npm publish --tag canary. (Including the tag is vital to ensuring this release doesn't end up tagged as latest — thus triggering a round of auto-update PRs in the various apps that consume Reaction)

  4. Confirm the results of the previous step with npm dist-tag ls. You should see something like

    canary: 22.9.8-canary-<your PR number>
latest: 22.9.7

  5. Over in Force install the canary with yarn add @artsy/reaction@canary

From here on out follow the steps in the next section for launching a Force review app. When you are done with the review process revert your change in step 2 above so that Reaction will resume normal versioning.

If your unmerged changes are in Force

Launching a Force review app can be automated via the build_review_app.sh script:

./scripts/build_review_app.sh review-app-name

When this process is done (and it will take a while) it should output a url similar to

a99199101d01011e9aff2127c3b176f7-1359163722.us-east-1.elb.amazonaws.com

This is your Review App url, which should support all of the basic features inside of Force.

If you'd like a pretty URL subdomain or need to test full OAuth flows (for, say, login redirects between Gravity and Force for Auction registration) then an additional non-automated step is required via Cloudflare:

  1. Login to Cloudflare, and navigate to artsy.net > DNS
  2. Click + Add Record
  3. Change Type dropdown to CNAME
  4. Under Name enter a new subdomain
  5. Under Target paste in URL output by build_review_app.sh script
  6. Hit Save
  7. DNS will propagate and after a few minutes the review app will be available via <your-subdomain>.artsy.net

Read over the build_review_app.sh script for more info on how this is all done.

😇 After your review app is no longer needed please remember to clean up any CNAMEs you've created, and to de-provision the review app itself with hokusai review_app delete <review-app-name>

Create a Topic Branch

Make sure your fork is up-to-date and create a topic branch for your feature or bug fix.

git checkout master
git pull upstream master
git checkout -b my-feature-branch

Write Tests

Write tests for all new features and fixes using Mocha or Jest. Run all tests with yarn test.

Mocha looks for files prefixed with .test or .spec, while Jest looks for the prefix .jest.

To speed up your workflow try watching an individual file for changes, e.g. yarn mocha -- --watch desktop/components/foo/bar.test.coffee

Write Code

We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.

Implement your feature or bug fix.

Commit Changes

Make sure git knows your name and email address:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Push

git push origin my-feature-branch

Make a Pull Request

Go to https://github.com/contributor/force and select your feature branch. Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days.

Rebase

If you've been working on a change for a while, rebase with upstream/master.

git fetch upstream
git rebase upstream/master
git push origin my-feature-branch -f

Check on Your Pull Request

Go back to your pull request after a few minutes and see whether it passed muster with Semaphore. Everything should look green, otherwise fix issues and amend your commit as described above.

Be Patient

It's likely that your change will not be merged and that the nitpicky maintainers will ask you to do more, or fix seemingly benign problems. Hang on there!

Thank You

Please do know that we really appreciate and value your time and work. We love you, really. <3