Skip to content

Latest commit

 

History

History
348 lines (289 loc) · 18.6 KB

CONTRIBUTING.md

File metadata and controls

348 lines (289 loc) · 18.6 KB
Raw

OperationCode Frontend

This is OperationCode.org's repository for their new front-end implementation using React.js

Before contributing, please review our GitHub Workflow.

Table Of Contents

Quick Start Guide

With an open source project involving contributors of varying levels of experience, it's difficult to create a one-size-fits-all guide. However, if if you feel confident with navigating your command line interface (CLI), please follow these step-by-step instructions. 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.

If you're unfamiliar with any of the instructions, you can navigate the rest of this guide to figure out the relevant technology and potential environment issues. If an instruction begins with "Run ...", that means to type the text in place of ... within your CLI.

Lastly, if you run into any problems with the following instructions, please try to communicate with us on Slack. You can get an invite to our Slack channel by requesting to join Operation Code. Once in our Slack team, simply type: /open #oc-projects and then click enter.

GitHub Workflow

  1. Before working on an issue, post a comment on the issue asking to claim it. One of our maintainers will assign themselves as a placeholder on the issue, at which point you are good to start working on it.
  2. Fork the Operation Code Frontend repo. Create a feature branch on your forked repo for the issue you are working on, and commit your work to that branch.
  3. Submit a pull request within two weeks of claiming the issue.
  4. Please do not ask to claim an issue or submit pull requests for an issue that someone else is currently assigned to.

Forking and Cloning this repository

  1. Click on the 'Fork' button on the top right corner of the page. You'll have your own copy of the repository available on your Github account.
  2. Go to the forked repository page on your Github account.
  3. Click on the green 'Clone or download' button and copy the link. Your link will look like https://github.com/<your_username>/operationcode_frontend.git. (Use the HTTPS link. Click here for more info).
  4. Open a terminal on your system and move to the directory where the repository should be.
  5. Run git clone <paste the link here>. You'll now have a local copy of the repository.
  6. cd to the repository.
  7. Run git remote add upstream https://github.com/OperationCode/operationcode_frontend.git. Note: You may replace 'upstream' with any nickname you'd like to give to the original repository. Run git remote -v to check if both the repositories are listed.
  8. Now you may make changes, add and commit to the repository.

Initial Install

  1. Run node -v. If you do not have version 6 or greater, go to nodejs.org and install the latest stable build.
  2. Run npm -v. If you do not have version 4 or greater, run npm install -g npm
  3. Run yarn --version. If you do not have version 0.21 or greater, run npm install --global yarn.
  4. Fork and clone the repository.
  5. Move into the repository
  6. Run yarn install

Addressing An Issue

Every time you want to resolve an issue, you'll need to create a branch, code there, and then submit a pull request (PR) for review. Assuming you're already in the /operationcode_frontend directory...

  1. Run git checkout -b "Name-of-branch-relevant-to-issue"
  2. Run yarn start and now your development environment will load. Happy coding!

When finished, create a PR on GitHub.

Returning To Work After A Break

Some issues take awhile to code a solution for. Just because you're working on an issue doesn't mean everybody puts their work on hold for you! You'll want to continually rebase your branch to ensure that your PR will have a seamless merge. Assuming you're ready to code again and you're already in the /operationcode_frontend directory...

  1. Keep your fork in sync with Operation Code's master branch.
  2. Run yarn install
  3. Run yarn start

Technologies

Here is a breakdown and summary of the main technologies our project utilizes:

  • NodeJS - Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine. React utilizes a tiny Node/Express server for it's development environment.
  • React.js - Facebook's popular JavaScript front-end framework.
  • Create-React-App - Create React App was initially used to handle boilerplate. We have since ejected and customized some of the scripts.
  • Webpack - Webpack acts as a module bundler and almost entirely dispenses with the need for a task runner, like Grunt or Gulp.
  • Babel - JavaScript compiler to unify all the different versions of JS that may have been used or will be used in the future. Here's a blog post from Scotch.io on why JavaScript utilizes "transpiling" with Babel.
  • Yarn - Facebook's open source JavaScript package manager. When NPM updated to version 5, it cut down on many its differences. Yarn is virtually identical to NPM, but it's still faster in installing dependencies - so we still recommend its usage.
  • CSS Modules - CSS Modules allow us to encapsulate CSS within components. Instead of HTML/CSS - our project structure is basically JSX/CSS.

Getting Started

Brush up on Development Tools

Git and basic Command Line

You will be working with Git and Github to manage source code. Understanding the basics and how to set things up will be helpful.

Getting comfortable with the Bash Shell will be helpful for both Windows and Mac. You may also want to learn about the Windows Command Prompt if you are using Windows.

NodeJS

The OperationCode front end runs on NodeJS. Learning the basics of NodeJS will be helpful.

Development Environment

You will need a few technologies installed in order to build and run this application. The installation of these is not always straightforward, but we will do our best to guide you through the process.

The installation will depend on which operating system you are running.

MacOS

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

Homebrew

  • Homebrew website
  • Paste the code below into a terminal window to install homebrew.
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

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.

NodeJS

You can install NodeJS a few different ways. Again, the easiest way to install it is with homebrew. We're going to install the latest of version 6 (it's the latest, stable build at the time of typing these instructions):

brew install node@6

Another option is to install Node Version Manager, this is helpful if you need to use multiple versions of node for different projects.

n is another project that manages node versions with possibly an easier install and less maintenance. -n

The other option is to install the nodejs package from the official website

Windows

Git

  • Install the full version of CMDER. This is a versatile terminal that wraps bash-like commands around Command Prompt by using Git for Windows. You have many options for getting Git on Windows. We recommend using Git for Windows as it gives you a bash shell which can be very powerful and help you start to learn linux commands.

Install the LTS version Node.js.

Follow the steps found in the Quick Start Guide

If you have any errors, make sure Node, npm, and Yarn is in your environment path by typing PATH in CMDER. Look for any path like the ones listed below. {USER} is your username you used to login into the computer.

  • C:\Program Files\nodejs\
  • C:\Program Files (x86)\Yarn\bin
  • C:\Users\{USER}\AppData\Roaming\npm
  • C:\Users\{USER}\AppData\Local\Yarn\bin
  • C:\Program Files\Git\usr\bin

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 front-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.

NodeJS

There are many ways and guides to install NodeJS on Windows. The resources below are from Microsoft.

One way to install NodeJS for windows is to simply download and execute the MSI Package from the official downloads page.

To test the installation open up a Command Prompt or Git Bash and enter the following commands:

node --version
npm --version

If your installation was successful you will get the versions of node and npm that were installed.

Developing Operation Code Frontend

File Structure

├── CONTRIBUTING.md
├── Dockerfile
├── LICENSE.md
├── Makefile
├── README.md
├── bin
│   ├── publish
│   └── run_backend.sh
├── config
│   ├── env.js
│   ├── jest
│   ├── paths.js
│   ├── polyfills.js
│   ├── webpack.config.dev.js
│   ├── webpack.config.prod.js
│   └── webpackDevServer.config.js
├── docker-compose.yml
├── index.html
├── jsconfig.json
├── mockServices
│   └── idme.js
├── node_modules
│   └── DEPENDENCIES...
├── package.json
├── pipeline
│   ├── docker_image
│   └── docker_staging_tag
├── public
│   └── IMAGES...
├── scripts
│   ├── build.js
│   ├── start.js
│   └── test.js
├── server.js
├── src
│   ├── App.js
│   ├── App.test.js
│   ├── config
│   ├── fonts
│   ├── images
│   ├── index.css
│   ├── index.js
│   ├── scenes
│   └── shared
├── stories
│   └── COMPONENT LIBRARY...
└── yarn.lock

Scenes / Component Structure

The idea of scenes were inspired by this post:

Scenes give us the ability to have different views of our application. For example, we could have a home page view, or a mentors page view with a different navigation menu.

Components

Components should be nested in a scene, or within another component. The idea is that a component will be declared at the level that it will be shared. If a component can be shared across the whole site, it should go in the /shared folder.

Styles

We are using CSS Modules for styling. Each components styles should be next to the component, and contain all the information to render that component. React favors Composition over Inheritance

Example...

├── scenes
│   └── home
│       ├── about
│       │   └── about.js
│       ├── families
│       │   ├── facts
│       │   └── jumboQuote
│       ├── footer
│       │   ├── footer.css
│       │   └── footer.js
│       ├── header
│       │   ├── logo
│       │   ├── topNav
│       │   ├── header.css
│       │   └── header.js
│       ├── landing
│       │   ├── landing.css
│       │   └── landing.js
│       ├── home.css
│       └── home.js
Code School Images

Code school logos belong in the following directory:

├── src
│   └── public
|         └── images
│               └── codeSchoolLogos
│                       └── LOGOS.jpg...

The following process should be used to prepare a code school logo for use:

  1. Find the highest-quality image file of the code school's logo
  2. Open some photo manipulation software (e.g. Photoshop, pixlr.com, Paint)
  3. Create a 200x200 pixel white square
  4. Paste the logo centered into the square
  5. Ensure that there is at least a 15 pixel margin between every edge and the logo
  6. Re-ensure that your logo is centered in the square
  7. Save the file as a JPEG (.jpg) in the above directory

Running the development environment

Now that you understand the technology and project structure, feel free to direct yourself to the Quick-Start Guide.

Production Builds

Static Site

  • yarn run build - This bundles the application into static files for production (minimization, post-processing, etc.)

  • yarn test - This starts the test runner.

  • yarn start:server - Runs express js serving production static files.

Docker Container

  • docker-compose up -d --build - Builds and starts the Docker Container listening port 80.

Resources

Contribute

Operation Code Contribution Guide

License

MIT © OperationCode