Skip to content

Latest commit

 

History

History
311 lines (218 loc) · 14.3 KB

CONTRIBUTING.md

File metadata and controls

311 lines (218 loc) · 14.3 KB
Raw

Guide To Contribution

Firstly, thank you for considering contributing to our project! It's people like you that make Operation Code such a great community.

The team at Operation Code wants to reiterate that joining our Slack team is the ultimate way to set yourself up for success when contributing to our repository. You can get an invite to our Slack channel by requesting to join Operation Code. Once in our Slack team, simply type: /open #oc-python-projects and then click enter. Feel free to ask for help; everyone is a beginner at first 😸!

This guideline is for newer developers, developers who are unfamiliar with the quick start instructions, and developers who are unfamiliar with Ruby. This guide assumes that you only have a passing familiarity with the command line and are comfortable in our OS of choice.

Reading this entire guide not only helps you contribute successfully into our codebase, it also helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.

We're an open source project and we love to receive contributions from our community — you! There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into the website itself.

Being an open source project involving contributors of varying levels of experience, it's difficult to create a perfect guide. Please note: most of the following instructions are not relevant to many Windows users - you'll need to research the equivalent of each command knowing what terminal you use on your Windows platform.

Lastly, If an instruction begins with "Run ...", that means to type the text in place of ... within your command line interface.

Table Of Contents

Git and GitHub

Git

There are many resources in the wild to learn about all forms of version control, including git. If none of the available resources have helped you, please join the #git channel on our Slack team for assistance.

GitHub Workflow

Click to Expand
  1. While not required, before working on an issue you may want to post a comment on the issue asking to claim it.
  2. Once you've claimed an issue, feel free to fork the repository
  3. If you follow all of the instructions in the help article above, you'll be able to create a branch. That's git checkout -b YOUR_BRANCH_NAME Note that some companies and organizations have branch-naming conventions - we do not.
  4. Once you make a branch, you're free to open your preferred text editor and code. If you don't have a preferred text editor, Operation Code recommends Pycharm and Visual Studio Code (more commonly referred to as "VS Code" and not to be confused with Visual Studio). You'll want to follow along with development workflow to see how you should go about coding in the repository.
  5. When your changes are complete, commit your changes. If you use git commit often, you'll notice your commit is taking longer than usual! That's because we have a "pre-commit hook". This hook is linting, formatting (example: changing tabs to spaces), and testing all of your changes. If a test fails, so does the commit. If your code had changes after formatting, you'll need to re-stage those file(s) and use git commit --amend to add the linted/formatted code to your original commit.
  6. After committing, push your branch to your forked repository. git push -u origin YOUR_BRANCH_NAME should do the trick.
  7. Create a pull request within two weeks of claiming the issue, using that branch on your fork.

Explanations

What Is The Front-End?

When you visit our website you're interacting with two systems, a front-end application and a back-end API. The front-end application is responsible for displaying the "User Interface" - images, text, animations... everything you interact with visually or physically on our web page. Front-end applications are usually written using a combination of HTML, CSS, and JavaScript and utilize one or more frameworks such as Angular, Vue, and React. We use React.

"front-end" is synonymous with client, client-side, "the view", and "the UI".

What Is The Back-End?

The back-end is responsible for providing data for the front-end to display. This sometimes involves processing the data entered into the front-end, and running various jobs like inviting new users to Slack, or signing them up for our newsletter. Our back-end is written with Python and Django and it's source code can be viewed here. It acts primarily as a "REST API".

"back-end" is synonymous with server, server-side, and "models & controllers"

What is REST? What is an API?

What is REST?

What is an API?

Development Workflow

Setting Up Your Environment

Click to Expand In order to work on the backend of the **Operation Code** site, you will need to install a few things.

There are three options for local setup:

Finding An Issue

Click to Expand
  • 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.

    Beginner friendly

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

    Roadmap

    High level overview of upcoming Operation Code goals. This is the source of upcoming issues.

    Working On Your Issue

    • Please first read Operation Code's guidelines for working an 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

Returning To Work After A Break

Click to Expand Some issues take awhile to code a solution for. It is very normal to take a large amount of time to turn in well-written work that resolves an issue! In the meantime, there could be many other people contributing to the code base. Since we use Git, you'll want to keep you project up-to-date with the `master` branch so there are no [merge conflicts](https://help.github.com/articles/about-merge-conflicts/) to resolve when you make your pull request.
  1. Keep your fork in sync with Operation Code's master branch.

API Documentation

We are using OpenAPI for documentation. The docs are automatically generated based on the code in the repository. To use, navigate to https://api.operationcode.org/docs/

Resources

Navigating Operating System Differences

MacOS

Click to Expand

Update Your Mac

If possible, we highly recommend updating to the latest version of MacOS.

If your machine has limitations on the operating system it can run, know that our development has been tested and works on MacOSX Yosemite v10.10.5. If you are utilizing an older version of MacOSX, we ask that you continue to progress through the tutorials and let us know if everything works out okay for you. We're interested in finding the oldest Mac Operating System required to develop on this project, but it is difficult to test.

Please file an issue to update this README.md if you use an older OS and were able to navigate installation instructions.

Xcode Command Line Tools

If you have xcode installed ensure that it is updated to the latest version through the app store.
The full xcode package is not required for the command line tools.

Running the following in your terminal window should prompt you to install the xcode command line tools if you don't already have it installed.

gcc

You can verify installation with the command below, you should see similar output:

gcc --version
Configured with: --prefix=/Library/Developer/CommandLineTools/usr --with-gxx-include-dir=/usr/include/c++/4.2.1
Apple LLVM version 6.0 (clang-600.0.54) (based on LLVM 3.5svn)
Target: x86_64-apple-darwin14.0.0
Thread model: posix

Git

The easiest way to install git is with homebrew.

brew install git

You can also install Github Desktop for the Graphical interface into github.
There is no need to install the Command Line tools if you installed git with homebrew.

Windows

Click to Expand

Git

Download and install Git for Windows from https://git-scm.com/download/win

Python

Download the latest version of python at https://www.python.org/downloads/, (3.7.3 at time of writing)

Follow the steps found in the Quick Start Guide

Occasionally you will deal with path issues this is fixed within windows by adding the appropriate key value pair to the path.

To add them in your path, you can go to your Control Panel by clicking on the Start > type in: Control Panel > click on System and Security > click on System > on the left hand side, click on Advanced System Settings > near the bottom of the window, click on the Environment Variables and then under the User variables for {USER} click on the Path table and click on Edit...

Now add those paths one at a time that are listed above into your user environment path if they are not already there. This is assuming you are installing in the default folders during the installation of the programs used on the back-end.

You can also install Github Desktop for a GUI Interface to Github. If you do this you don't want to install the Command Line tools, as CMDER and Git For Windows are more recent versions.