## 1. Project Overview & Quickstart (dustinspecker/contributing)

# contributing

Open-source repository dustinspecker/contributing

### Repository Details
- **Repository:** [dustinspecker/contributing](https://github.com/dustinspecker/contributing)
- **Primary Language:** Code

*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*

## 2. Official Technical Reference & Guides (dustinspecker/dustinspecker.github.io)

## File: _config.yml

# Welcome to Jekyll!
#
# This config file is meant for settings that affect your whole blog, values
# which you are expected to set up once and rarely need to edit after that.
# For technical reasons, this file is *NOT* reloaded automatically when you use
# 'jekyll serve'. If you change this file, please restart the server process.

# Site settings
title: Dustin Specker
email: dustinspecker@gmail.com
  Dustin Specker's blog.
baseurl: "" # the subpath of your site, e.g. /blog
url: "http://yourdomain.com" # the base hostname & protocol for your site
twitter_username: dustinspecker
github_username:  dustinspecker

# Build settings
markdown: kramdown

---

## File: about.md

---
layout: page
title: About
permalink: /about/
---

Sharing what I learn, mostly in the JavaScript community.

---

## File: _drafts/jsx-pragma.md

---
layout: post
title: Creating a JSX Pragma
---

JSX is a neat syntax, but can cause confusion to users that aren't quite familiar with how the JSX transformer works.

Babel converts JSX such as the following:

```javascript
import React from 'react'

export default props =>
  <div title='hi'>
    <ul>
      {props.items.map(item =>
        <li>{item.name}</li>
      )}
    </ul>
  </div>
```

to:

```javascript
import React from 'react'

export default props =>
  React.createElement(
    'div',
    {title: 'hi'},
    React.createElement(
      'ul',
      null,
      props.items.map(item =>
        React.createElement(
          'li',
          null,
          item.name
        )
      )
    )
  )
```

The JSX transformer convert JSX into function calls. This function is the JSX pragma. A JSX pragma accepts a tag name, an attributes object, and the rest of the arguments passed are the element's children.

With this in mind, we can easily create our own JSX pragma.

First, let's handle only the tag name. We'll create a function accepting a tag name that returns an element of that type.

```javascript
const docCreateElement = tag => {
  const element = document.createElement(tag)

  return element
}
```

Next, let's handle accepting an attributes object.

```javascript
const docCreateElement = (tag, attrs) => {
  const element = document.createElement(tag)

  Object.keys(attrs).forEach(attr => {
    element.setAttribute(attr, attrs[attr])
  })

  return element
}
```

Next, let's handle attaching event handlers via the attrs object.

```javascript
const docCreateElement = (tag, attrs) => {
  const element = document.createElement(tag)

  Object.keys(attrs).forEach(attr => {
    if (typeof attrs[attr] === 'function') {
      // convert `onClick`, etc. to `click`
      const eventName = attr.slice(2).toLowerCase()
      element.addEventListener(eventName, attrs[attr])
    } else {
      element.setAttribute(attr, attrs[attr])
    }
  })

  return element
}
```

Next, let's handle appending children to the created element.

```javascript
const docCreateElement = (tag, attrs, ...children) => {
  const element = document.createElement(tag)

  Object.keys(attrs).forEach(attr => {
    if (typeof attrs[attr] === 'function') {
      // convert `onClick`, etc. to `click`
      const eventName = attr.slice(2).toLowerCase()
      element.addEventListener(eventName, attrs[attr])
    } else {
      element.setAttribute(attr, attrs[attr])
    }
  })

  children.forEach(child => {
    if (typeof child === 'string') {
      element.appendChild(document.createTextNode(child))
    } else {
      element.appendChild(child)
    }
  })

  return element
}
```

---

## File: _posts/2016-04-22-semantic-release.md

---
layout: post
title: Setting up Semantic Release
---
[](https://github.com/semantic-release/semantic-release)

# Introduction to Semantic Release
[Semantic Release](https://github.com/semantic-release/semantic-release) aims to automate and ease the npm publishing process.

When setup, it automates the following steps of a release:

1. Verify tests are succesful
1. Bump the package version in `package.json`
 - Semantic Release analyzes commits to determine if a patch, minor, or major should be bumped. By default Semantic Release expects commits to be appropriately labeled as a fix, new feature, or a breaking change.
1. Create a Git tag for the new version **with a change log**
 - The change log generation also examines the commit messages to determine any fixes, new features, or breaking changes.
1. Push the newly created tag to the project's Git repostiory
1. Perform a `npm publish`

# Set Up
Setting up Semantic Release on an existing npm module is simple.

1. Run `npm install semantic-release-cli` to install the Semantic Release command line tool.
 - This tool will be used to modify a project's `.travis.yml` and `package.json`.
1. In the npm package's directory, run `semantic-release-cli setup`.
 - It will ask a few questions about the project. It will also ask for your GitHub and npm credentials. It will then create a [Personal access token](https://github.com/settings/tokens) on GitHub for write permissions to the repository.

The setup process will result in a few changed files.

First, the `package.json` will include a `semantic-release` `devDependency`. There will also be a `semantic-releae` npm script created. Also, the `version` key will be missing from `package.json`. Semantic Release will add the version key right before performing the `npm publish` later on. Some Semantic Release users opt to have a `version` key with a value of `0.0.0-semantically-released` or similar to signify that an automated release is expected.

Next, `.travis.yml` will have a recommended configuration and will execute the `semantic-release` npm script.

At this point, it is fine to commit these changes. The setup for Semantic Release is complete.

# Using Semantic Release

From now on, Semantic Release will automatically run on Travis CI on every new commit pushed to the `master` branch. Semantic Release expects a particular Git commit message style, the Angular style.

A few examples of Angular style commits:

 - `feat(home): add link to user settings`
 - `fix(nav): prevent error when user submits empty form`
 - `docs(readme): add code coverage badge`

[Commitizen](https://github.com/commitizen/cz-cli) is a great tool for interactively creating this style of commits.

Any breaking changes should have the following format:

```
feat(add): accept only positive numbers

BREAKING CHANGE:

The add function now long accepts positive numbers. Passing
negative numbers will result in an `Error` being thrown.
```

Semantic Release is looking for `BREAKING CHANGE:` in commit messages to determine if the commit is a breaking change. **A potential gotcha is omitting the `:` and writing `BREAKING CHANGE` will prevent Semantic Release from determining the commit is a breaking change.**

# Gotcha Encountered

One gotcha that bit me for a while is the format of `repository` in `package.json`.

Instead of using the short form

```json
{
  "repository": "dustinspecker/package"
}
```

Semantic Release is expecting the long form

```json
{
  "repository": {
    "type": "git",
    "url": "https://github.com/dustinspecker/package.git"
  }
}
```

If `semantic-release-cli setup` hangs after answering the prompts I would recommend checking the `repository` field.

# Further Steps

There exist a few plugins for Semantic Release with more being actively developed. A few note-worthy ones:

 - [Cracks](https://github.com/semantic-release/cracks) - Runs the current release's tests against the next release's source. If these tests fail then the change is a breaking change.
 - [dont-break](https://github.com/semantic-release/semantic-release/issues/65) - The early phases of a plugin that runs the test suites of packages that depend on the package to be published. If these tests fail then a change is probably a breaking change.
- [india](https://github.com/semantic-release/semantic-release/issues/66) - India aims to analyze any JSDoc comments to determine breaking changes.