Skip to content

Latest commit

 

History

History
471 lines (299 loc) · 27.6 KB

CONTRIBUTING.md

File metadata and controls

471 lines (299 loc) · 27.6 KB
Raw

Contributing to Exercism.io

First of all, thank you for helping with Exercism.io!

We are working to improve this document, and if you find any part of it confusing, or if you can't figure out how to get started with something, then rest assured it's not you, it's us! Please open up a new issue to describe what you were hoping to contribute with, and what you're wondering about, and we'll figure out together how to improve the documentation.

Finding Your Way

I see a problem I have an idea I would like to help
I see a problem I have an idea I would like to help

--

I see a problem

on the website with the command-line client (CLI) getting started with a language with a specific exercise
I see a problem on the website I see a problem with the CLI I see a problem getting started with a language I see a problem with a specific exercise

I see a problem on the website

  • If you're having trouble figuring out how to do something on the website, jump in the online support chat and ask there.

I see a problem with the command-line client (CLI)

  • If you're having trouble installing or working with the CLI, ask for help in our online support chat.

I see a problem getting started with a language

  • If you're having trouble with the setup instructions, ask for help in our online support chat.

I see a problem with a specific exercise

  • If there's a defect in the...

  • You can ask for help within the track:

    1. exercism submit the code you have;
    • Follow the link that the CLI returns to view your new submission on the website;
    • In the "Manage" pull-down (top-right), select "Request Help".

    When you do this, your submission is highlighted, letting others know you're stuck.

I have an idea

making the website better improving the command-line client (CLI) a brand-new exercise for Exercism improving an existing exercise
Making the website better Improving the command-line client A brand new exercise for Exercism Improving an existing exercise

I have an idea about making the website better

Is it around a portion of the site we're currently talking about? Jump in!

Current specific discussions:

Here are some helpful starter searches in the two repositories that contain ideas about the website:

If the idea doesn't fit in one of those discussions, then if it relates to:

I have an idea about improving the command-line client (CLI)

Current specific discussions:

Here are some helpful starter searches in the two repositories that contain ideas about the CLI:

If the idea isn't being discussed yet, kick it off in the exercism/cli repository.

I have an idea about a brand-new exercise for Exercism

New exercise ideas are definitely welcome! Here's how to ensure the idea lands in the right place:

Note: the central library of exercises on Exercism is https://github.com/exercism/x-common.

I have an idea about improving an existing exercise

  • If the idea is to improve the...
    • instructions of the exercise, you can make a difference by making the suggestion in the exercism/x-common repository.
      • if you have the time and the desire, you can help even more by fixing it.
    • tests or starter code of the exercise, you can help by making the suggestion in the "Issues" section of the corresponding language repository.
      • if you have the time and the desire, you can help even more by fixing it.

I would like to help

Thank you!

You have (or want to improve your) skills in

| technical writing and organization | fluency in a particular programming language | web programming | Ruby | Go | web design | mentoring others |:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| | organizing stuff | fluency in a particular programming language | web programming | Ruby | Go | web design | mentoring others

I would like to help; I can / want to get better at technical writing and organization

I would like to help; I am fluent in / want to get better at a particular programming language

Are you a language enthusiast? Help other people fall in love with your language by...

Mentoring Others

Contributing to a Language Track

This means helping maintain the code of the exercises and supporting tooling for a particular language.

  • Find a language you love or want to get to know better: http://exercism.io/repositories

  • Orient yourself through our [Getting Involved in a Track] (docs/getting-involved-in-a-track.md) guide.

I would like to help; I know / want to get better at web programming

Do you have/want to have chops in HTML+CSS+JavaScript/CoffeeScript and want to improve the feel and function of the Exercism website?

  1. Setup your local development environment.

You may also find these helpful:

I would like to help; I know / want to get better at Ruby

Do you have/want to have chops in Ruby or Sinatra and want to add to the website?

  1. Setup your local development environment.

You may also find these helpful:

I would like to help; I know / want to get better at Go

One of the more subtle but important parts of the Exercism experience is our CLI; it's written in Go.

  1. Setup your local development environment for the CLI: exercism/cli.

You may also find these helpful:

I would like to help; I know / want to get better at web design

Do you love making enticing user experiences? Help us rethink our user experience (UX)!

I would like to help; I know / want to get better at mentoring others

Do you like mentoring people?

Table of Contents

Code of Conduct

Help us keep exercism welcoming. Please read and abide by the Code of Conduct.

The Ecosystem

Exercism consists of two main parts:

  • the website - where the conversations happen (this repository)
  • the command-line interface (CLI) - to fetch exercises and submit solutions exercism/cli

Behind the scenes we also have:

  • language tracks - one repository per language see list
  • problem metadata - a shared repository for all languages exercism/x-common
  • the problems API - serves the exercise data exercism/x-api
  • rikki- the robot - provides automated feedback on certain exercises exercism/rikki

Contributing

We curate issues that we think are good for starting out into exercism/todo.

If you want to work on the exercism.io website codebase, then continue reading this guide.

To contribute to one of the language tracks, check out the Language Track Guide.

For details about working with the problems API, check out the Problems API Guide.

Submitting Code Changes

These instructions should get you closer to getting a commit into the repository.

See the Setting up Local Development guide for more information about how to run exercism.io locally.

Git Workflow

  1. Fork and clone.
  2. Add the upstream exercism.io repository as a new remote to your clone. git remote add upstream https://github.com/exercism/exercism.io.git
  3. Create a new branch git checkout -b name-of-branch
  4. Commit and push as usual on your branch.
  5. When you're ready to submit a pull request, rebase your branch onto the upstream master so that you can resolve any conflicts: git fetch upstream && git rebase upstream/master You may need to push with --force up to your branch after resolving conflicts.
  6. When you've got everything solved, push up to your branch and send the pull request as usual.

Issues

We keep track of everything around the repository using GitHub issues.

Good First Patch

We're trying to label issues with "good first patch" if we think that these can be solved without too much context about exercism.io's codebase or functionality. To find them, you can do an organization-wide search.

Labels

[TODO: explain the various labels as we settle on useful ones]

Style (Ruby)

We have Rubocop integrated. It is based on the Ruby Style Guide. Help keep us our code clean by following the style guide. Run the command rubocop to check for any style violations before submitting pull requests.

Style (JS/CSS)

If you have any JS or CSS changes, please run cd frontend && lineman spec-ci to check for any style violations before submitting pull requests.

Pull Requests

When submitting a pull request, sometimes we'll ask you to make changes before we accept the patch.

Please do not close the first pull request and open a second one with these changes. If you push more commits to a branch that you've opened a pull request for, it automatically updates the pull request. This is also the case if you change the history (rebase, squash, amend), and use git push --force to update the branch on your fork. The pull request points to that branch, not to specific commits.

Exercism Web Structure

Intro

Exercism is built with the Sinatra web framework. If you haven't heard of it, definitely check it out. It's a lightweight web framework for Ruby.

Exercism seems to follow what some may call an MVP (Model-View-Presenter) architecture. Read more about that here.

Core Directories

API

API contains routes which are used by the JavaScript frontend and the CLI. The routes here are similar to the one's in app/ in that they're individual Sinatra apps that inherit from the Core API route (api/v1/routes/core.rb). If you add a route, it needs to be added to api/v1/routes.rb and api/v1/v1.rb.

App (Routes, Presenters, Helpers and Views)

App is the user facing side of Exercism. It handles logging in (and other functions), making calls out to the database to store or get information, structuring HTML (that can later be styled), etc.

Helpers can be anything that helps presentation of data. For Exercism, these are things like: wrappers for Markdown and Syntax Highlighting parsers, session handling, etc. Helpers are defined in individual modules under app/helpers/*. The full list of helpers is in app/helpers.rb, and if you add a new helper, this file needs to be edited. The convention is ClassName: 'filename'.

Presenters are for showing information that would be beneficial to users or the views but maybe not the best way to store data. For example, in Exercism, most times are stored in UTC (generally most servers store time this way) but... users might want to see times in their own timezone. Presenters can take relevant information (like showing comment notifications on the dashboard) and transform it to be more personal. This convention hasn't been strictly enforced so that description varies between presenters. Presenters are defined in individual classes/modules under app/presenters/*. The presenters are loaded into the app in the app/presenters.rb file, and if you add a presenter, it needs to be added to that file. The convention is ClassName: 'filename'.

Routes in Sinatra are kind of like a combination of routes and controllers in Rails. Each route file contains an individual Sinatra app that inherits some behavior from Core (found in app/routes/core.rb). In a route file, you can specify endpoints (like exercism.io/login) and define how the app should respond (i.e. accept some credentials and log the user in or handle errors accordingly). Routes are defined in individual modules under app/routes/*. The route files are loaded into the app with the app/routes.rb file, and if you add a route file, it needs to be added to that file. The convention is ClassName: 'filename'. Routes are unique in that you'll also have to update the main app.rb with the new app info. The convention is Routes::ClassName.

Views are a collection of templates that create html. Templates are a way to embed Ruby in your views so that you can serve up information, iterate over items without repeating yourself (like creating tables of data), etc. The templating engine that Exercism uses is ERB.

Frontend (JavaScript, Custom Directives, Bootstrap, etc)

The client side is mostly written in CoffeeScript and uses frameworks like angular and bootstrap.

Frontend is where Exercism stores all of it's production client side code. Exercism doesn't have much JS (outside of bootstrap) but frontend/ does handle comment threads on submissions, markdown preview on comments, submission code (expanding and contracting), etc. If you suspect that there is frontend wizardry happening and you haven't seen it in bootstrap, most likely it's in here.

DB (Migrations)

To create a migration you can use rake db:generate:migration name=the_name_of_your_migration. That will create a new migration in db/migrate. For help, look at the other migrations or at docs for ActiveRecord migrations. If you add, remove or rename database columns, you may have to update the seeds as well. Exercism pulls seed data from another repo found here. The seed data provides placeholder information (like users, exercise submissions, comments, etc) to help with development.

Lib (DB Configurations, Application Logic, Models, Rake Tasks)

Application Logic can be anything that is used for the backend application (and, possibly, shared with the frontend as well) can live here. Maybe a library for GitHub OAuth, configurations for a Markdown parser and a syntax highlighter, etc.

Models are for connecting classes (e.g. User) and their attributes to database tables with ActiveRecord (ones that you set up with migrations), relating them to other tables (e.g. User has_many :posts) and adding other type functionality (e.g. validations).

Test

Tests follow the organization of the app. For instance, if you're writing a new route, it would go in test/app. You could write a test post or get and assert that you get back data that you expect. Read more about tests here.

Additional Directories

Bin (Tools)

Console provides a REPL (Read-Eval-Print-Loop) with the Exercism application logic pre-loaded. Want to see what it would look like to be a user that has done every exercise? Console. Want to test out a new feature but you haven't written the frontend for it? Console. A bit more info can be found here.

Setup is a script that you can run in order to create the development and test databases, makes sure all the apps dependencies (gems) are installed, etc.

Config

Database connection, bugsnag config and local development GitHub OAuth credentials.

Docs (Static Files for GitHub Docs)

Static files and pictures for hosting in the GitHub docs.

Public (Static Files for the Site)

Static files for the Exercism web app. Fonts, jQuery (public/js/app.js), icons, language images, and sass (styling).

X

X is a collection of scripts to organize and compile documentation for the many parts of exercism (cli, general help, product introduction, track info).

Future Roadmap

We focus our efforts on the roadmap.

Sometimes we get suggestions for things that would be great, but they're not part of locking down the core behavior of the app. In this case we'll close and label it "future roadmap" to make it easy to search for later.

For more resources see: