Skip to content

Latest commit

 

History

History
195 lines (149 loc) · 7.13 KB

CONTRIBUTING.md

File metadata and controls

195 lines (149 loc) · 7.13 KB
Raw

Contributing

Thanks for considering contributing to this project! Here are some guidelines to help speed and unify development.

Reporting Bugs or Issues

This project uses GitHub issues to track bugs, enhancements, and other tasks.

To create a new issue:

  1. Click on the Issues tab underneath the name of this repo, above.
  2. Click on the New Issue button on the right side of the page.
  3. Enter a title and description for the issue.
  4. If applicable, select a label on the right side (such as "bug").
  5. Click "Submit new issue".

The title should be a short label that identifies the bug or feature. The "Leave a comment" section should contain a description with as much detail as possible. For bugs or typos, this description might include:

  • Specific behavior for the bug and what behavior you expected
  • Steps someone else could take to reproduce the bug
  • Any console logs or other diagnostic information
  • Filenames and line numbers, if possible (especially for typos)

Making Code Contributions

Like many projects on GitHub, contributions should be submitted by creating a fork of the repo, making some changes there, and then submitting them as a Pull Request for review. You will find a detailed explanation of this workflow below. We are open to any help you'd like to give, but if you are looking for a good place to start, you might check out the Issues page to see if there is anything labeled "help wanted" that you could tackle.

Submitting Pull Requests

While the fork-to-PR process is common, this repo is somewhat unusual because master is not the branch you should make a PR against. In this repo, master is not the source of truth, but a collection of generated stub functions for students to fill out. The original source of this code is actually in the staging branch, so you should submit all PRs against this branch.

The complete PR process is as follows:

  1. Create a personal fork of this repository.
  2. Starting from staging, create a topic branch for your changes.
  3. Submit a pull request from the topic branch on your fork to staging on this repo.
  4. Add other developers as reviewers.
  5. Make changes as requested by rebasing the appropriate commits, and then force-pushing to your branch.

A pull request cannot be merged until all requests for changes have been addressed. After that, it must be approved by at least one project maintainer. The actual merge will be done by one of the maintainers.

Important: Maintainers should always use the "Create a merge commit" option, because rebasing destroys important commit history when the prompt and solution files are generated.

Commit Style

Commits should be as small as possible, but no smaller. Ideally, a commit should be an "atomic" change to the repo that adds a single new piece of functionality or fixes a single bug; if it were broken down to a smaller commit, it would not provide anything of value. This is a subjective measure, so use your best judgment.

For the commit message, follow Chris Beams's Seven Rules:

  • Separate the subject from the body with a blank line
  • Limit the subject line to 50 characters
  • Capitalize the subject line
  • Do not end the subject line with a period
  • Use the imperative mood in the subject line
  • Wrap the body at 72 characters
  • Use the body to explain what and why vs. how

In addition to these rules, the commit body should reference the number for the issue they address. For bug fixes, use the syntax Fixes #XXX. For enhancements, use the syntax Closes #XXX. This information can also go into the PR message.

Finally, each commit message must include a "Signed-off-by" line that includes your name and email. This sign-off indicates that you agree that the commit satisfies the Developer Certificate of Origin (DCO). Git can automatically add this signature by using the -s flag:

git commit -s

JavaScript Style

This project follows a slightly modified version of the Hack Reactor Style Guide. There is an .eslintrc.json file with these rules in the root project directory. Any contributor writing JavaScript code should install ESLint and run it on their code before submitting a PR. The easiest way to do this is to run:

npm install -g eslint
eslint ./

Prompt Generation Syntax

This repo uses special comment-based tags to differentiate between solution code and prompts. Later, these tags will be used to separate the prompts into the master branch, and the solution code into the solution branch. The syntax is a slightly more opinionated version of problemify. A typical example might look this:

const hello = name => {
  /* START PROBLEM
  // Your code here

  END PROBLEM */
  // START SOLUTION
  console.log(`Hello, ${name}`);
  // END SOLUTION
};

With the above stub function, the signature will appear in both the prompts and the solution code, but the body will be very different:

master:

const hello = name => {
  // Your code here

};

solution:

const hello = name => {
  console.log(`Hello, ${name}`);
};

Note that the comment-tags were removed from both versions. Also note that the publishing script errs on the side of caution. You must write each tag exactly: on its own line, with the correct style of comment, in all caps. Otherwise, it will be ignored. Different indentation is the only supported variation.

Use this syntax to mark an entire file as solution code:

/* SOLUTION FILE */
'use strict';

const bar = require('./foo');

// Do some stuff...

With this syntax, the entire file is removed from the master branch and published only to solution.

You can also use /* PROBLEM FILE */ to get the opposite effect. As with the other tags, make sure to enter it exactly, with same comment syntax and capitalization, on its own line. Unlike the other tags, you must not indent the file tags, and they must appear on the first line of the file.

Examples:

Publishing Updates to master and solution

Maintainers only: The bin/publish script does the work of parsing the tags and pushing the generated code to the appropriate branch.

Run this script periodically; preferably, after every PR is merged. Make sure that your working directory is clean when you run it, and never do any rebasing or force-pushing to upstream master or upstream solution. This script pushes to them directly, but should only ever make additions.

If there is a conflict, something has gone wrong and needs to be investigated.