Skip to content

Latest commit

 

History

History
178 lines (118 loc) · 9.01 KB

CONTRIBUTING.md

File metadata and controls

178 lines (118 loc) · 9.01 KB
Raw

Contributing to Operation Code

So, you want to learn how to program? Contributing to Operation Code is a great place to get started. This document will help you march from zero to deploying code in no time!

Table of Contents

  1. Quickstart
  2. Setting Up Your Environment
  3. Finding an Issue
  4. Working on Your Issue
  5. Submitting Your Changes
  6. Code Standards
  7. License

Quickstart

  1. Setting Up Your Environment
  2. Find an Issue To Work On
  3. Submit Your Pull Request

Setting Up Your Environment

  • In order to work on the Operation Code site, you will need to install a few things.

    Docker

    Docker is a container system. Click the link below to install Docker on your Operating System.

    Git

    Git is a distributed version control system. This is how our code is stored and managed. Git can be frustrating, but it is an essential tool. If you want to learn more about Git, a great resource is Think Like a Git. If you find yourself in a real git pickle, see "Oh, shit, git!".

    Make (for Windows only)

    Make is a tool which controls the generation of executables and other non-source files of a program from the program's source files. It is a standard part of the GNU library and is included in most distrubtions of Linux, as well as OSX. Unfortunately, Windows does not have a native make program, so it will need to be installed and added to PATH in order for the command line commands to work. You can use the GNUWin general installation guide as a general guide on how to install a GNU package and add it to PATH.

    Operation Code

    You are now ready for the actual Operation Code code base.

    • The common practice is to make a copy of the GitHub repository you want to work on (known as forking the repo), make your changes, and then request to merge those changes back into the project (known as a pull request).

    • Forking a repo is done through GitHub's web UI. It can be found in the top right corner of the Operation Code's GitHub page.

    • The following commands will pull down the source code from your forked repo.

    • Make sure to replace [YOUR-GITHUB-NAME] with your GitHub name. (example: https://github.com/iserbit/operationcode.git)

    Local Development Environment

    Fork the repo first.

    git clone https://github.com/[YOUR-GITHUB-NAME]/operationcode.git operationcode-upstream
cd operationcode-upstream
git remote add upstream https://github.com/OperationCode/operationcode.git

    Database Setup:

    To setup the database simply run the following command in the root directory of the project.

    make setup

    Running Operation Code:

    Operation Code has some handy shortcuts built in to make common tasks simple. You can check out the Makefile to see a full listing of what these shortcuts are and what they do.

    To run Operation Code simply type:

    make

    You can now visit http://localhost:3000 (or run make open) and you should see Operation Code running locally!

Finding An Issue

  • Now you have everything setup, you will need to find issues to work on. Operation Code uses Github's built in issue tracker. A listing of all our issues can be found here.

  • Familiarize yourself with the issue types below, and browse for an issue that you want to work on. Don't be afraid to ask for clarification or help.

  • Once you have found an issue, leave a comment stating that you plan to work on the issue. Once assigned to you, your mission is a go!

    Issue Types

    • Issue types are managed through labels. The below labels help us easily identify and manage issues with different workflows.

    bug

    Bugs are errors in code that produce unintended or unexpected results. In addition to the bug label, there may also be a tag indicating what the bug affects. For example issue#124 was a bug that affected the testing environment.

    feature

    Features either add new functionality or improve existing functionality.

    discussion

    Discussions will generally not have specific actionable items in them, and can be used to plan and design a feature.

    milestones

    Milestones are used as containers for new issues pertaining to a project, timeframe or feature.

    beginner-friendly

    These items are hand picked as being great candidates as your first issue to work on.

Working On Your Issue

  • From the forked and cloned repository on your environment, you can now create a feature branch. It is a good idea to name your branch after the issue it is attached to.

    git checkout -b <feature-branch-name>

  • You can check the branch your are currently working on by using the branch command.

    git branch

  • Once you have finished your work, head over to Operation Code's main GitHub page, and make a pull request. More information about pull requests can be found in the next section.

  • To return to your main master branch, type the following in the terminal:

    git checkout master

Submitting Your Changes

  • When you have completed work on your feature branch, you are ready to submit a pull request.

  • Each pull request should:

    • Be tied to a single issue
    • Be fully tested
    • Have its own tests
    • Not break existing tests

  • Once your pull request has been submitted, it will be reviewed by a core team member. This process helps to familiarize more people with the codebase, and provides a second set of eyes and perspective to your new feature.

  • If your code is accepted, it will be merged into the master branch. If all the tests pass, it will be automatically deployed to operationcode.org immediately.

  • Congratulations! You have made your first contribution!

    Bots

    • Each pull request is inspected by the following bots:

      • CodeClimate - Checks for style validation errors, insecure and problematic code on pull requests.

      • Travis - Runs the test suite on each check in, and deploys each change that gets merged.

    Add yourself

    • Once your pull requests has been merged, don't forget to add your name to the list of contributors in CONTRIBUTORS.md.

Code Standards

License