mercury-parser/CONTRIBUTING.md

Contributing to Postlight Parser

Thank you for your interest in contributing to Postlight Parser! It's people like you that make this such a useful tool. The below guidelines will help answer any questions you may have about the contribution process. We look forward to receiving contributions from you — our community!

Please read our Code of Conduct before participating.

Contents

• Contributing to Postlight Parser
  • Contents
  • Ways to Contribute
  • Reporting a Bug
    • Security
  • Requesting a Feature
  • Development Workflow
    • Building
    • Testing
    • Code Style
      • JavaScript
      • Markdown
    • Node.js Version Requirements
  • Writing Documentation
  • Submitting a Pull Request
    • Commit Style
    • Code Reviews
  • Helpful Links and Information

Ways to Contribute

There are many ways you can contribute to the Postlight Parser community. We value each type of contribution and appreciate your help.

Here are a few examples of what we consider a contribution:

• Updates to source code, including bug fixes, improvements, or creating new custom site extractors
• Answering questions and chatting with the community in the Gitter room
• Filing, organizing, and commenting on issues in the issue tracker
• Teaching others how to use Postlight Parser
• Community building and outreach

Reporting a Bug

While bugs are unfortunate, they're a reality in software. We can't fix what we don't know about, so please report liberally. If you're not sure if something is a bug or not, feel free to file a bug anyway.

If you have the chance, before reporting a bug, please search existing issues, as it's possible that someone else has already reported the error. This doesn't always work, and sometimes it's hard to know what to search for, so consider this extra credit. We won't mind if you accidentally file a duplicate report.

Opening an issue is as easy as following this link and filling out the template.

Security

If you find a security bug in Postlight Parser, send an email with a descriptive subject line to mercury+security@postlight.com. If you think you’ve found a serious vulnerability, please do not file a public issue or share in the Postlight Parser Gitter room.

Your report will go to Postlight Parser's core development team. You will receive acknowledgement of the report in 24-48 hours, and our next steps should be to release a fix. If you don’t get a report acknowledgement in 48 hours, send an email to mercury@postlight.com.

A working list of public, known security-related issues can be found in the issue tracker.

Requesting a Feature

To request a change to the way that Postlight Parser works, please open an issue in this repository named, "Feature Request: [Your Feature Idea]," followed by your suggestion.

Development Workflow

This section of the document outlines how to build, run, and test Postlight Parser locally.

Building

To build the Postlight Parser locally, execute the following commands:

# Clone this repository from GitHub.
git clone https://github.com/postlight/parser.git

# Navigate into the root of this repository.
cd parser

# Install local dependencies.
yarn install

# Run the node release
yarn build

# Build the web release
yarn build:web

Testing

Postlight Parser is a test-driven application; each component has its own test file. Tests are run for both node and web builds. Our testing frameworks are:

• Jest for the node build
• Karma for the web build

For new code to be accepted, all tests must pass in both environments. To run the required tests for local development, execute the following commands:

# Run the full test suite once, for both node and the browser
yarn test

# Run the tests for node build only
yarn test:node

# Run the tests for web build only
yarn test:web

# Run the tests in node, then re-run tests on file changes.
# If an optional <test_file> string is passed, only tests
# matching that string will be re-run.
#
# E.g., `yarn watch:test nytimes` will run the tests for
# `./src/extractors/custom/www.www.nytimes.com/index.test.js`
yarn watch:test <test_file>

Code Style

JavaScript

We use a slightly modified version of the Airbnb JavaScript Style Guide. To enforce this, all pull requests must pass ESLint before they can merge.

All code is also formatted with Prettier. This is done automatically when you commit code, so whether or not you use Prettier as you develop is up to you.

Markdown

In addition to enforcing a JavaScript style guide, we also require that Markdown files pass remarklint with the recommended preset. This helps keep our Markdown tidy and consistent.

Node.js Version Requirements

Postlight Parser is built against Node >= v12.8.1. Since this is the version we run in our CI environments, we recommend you use it when working on the codebase.

If you use nvm to manage Node.js versions and zsh (like Oh-My-ZSH), you can have nvm switch to the correct Node.js version automatically when you cd into this repository. To do so, add the following to your ~/.zshrc file:

# place this after nvm initialization!
autoload -U add-zsh-hook
load-nvmrc() {
  local node_version="$(nvm version)"
  local nvmrc_path="$(nvm_find_nvmrc)"

  if [ -n "$nvmrc_path" ]; then
    local nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")

    if [ "$nvmrc_node_version" != "N/A" ] && [ "$nvmrc_node_version" != "$node_version" ]; then
      nvm install
    fi
  elif [ "$node_version" != "$(nvm version default)" ]; then
    echo "Reverting to nvm default version"
    nvm use default
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc

Writing Documentation

Improvements to documentation are a great way to start contributing to Postlight Parser. The source for the official documentation are Markdown files that live in this repository.

Submitting a Pull Request

Want to make a change to Postlight Parser? Submit a pull request! We use the "fork and pull" model described here.

Before submitting a pull request, please make sure:

• You have added tests for modifications you made to the codebase.
• You have updated any documentation in the source code comments for APIs that you may have changed.
• You have no linter errors to correct after running yarn lint.
• You have run the test suite via yarn test and it passed.

Commit Style

Commit messages should follow the format outlined below:

prefix: message in present tense

Prefix	Description
chore	does not effect the production version of the app in any way.
deps	add, update, or remove a dependency.
doc	add, update, or remove documentation. no code changes.
dx	improve the development experience of parser core.
feat	a feature or enhancement. can be incredibly small.
fix	a bug fix for something that was broken.
perf	add, update, or fix a test.
refactor	change code, but not functionality.
style	change code style, like removing whitespace. no functional code changes.
test	add, update, or fix a test.

Code Reviews

Once you have submitted a pull request, a member of the core team must review it before it is merged. We try to review pull requests within 3 days but sometimes fall behind. Feel free to reach out to the core team if you have not received a review after 3 days.

Helpful Links and Information

Some useful places to look for information are:

• The main README for this repository.
• The Postlight Custom Parser README.
• The postlight/mercury room on Gitter
• The Postlight Parser API repository.

Adapted from Contributing to Node.js and ThinkUp Security and Data Privacy.