Skip to content

Latest commit

 

History

History
136 lines (93 loc) · 7.7 KB

CONTRIBUTING.md

File metadata and controls

136 lines (93 loc) · 7.7 KB
Raw

Contributing to Thimble

So, you'd like to contribute to Thimble - that's great, we're excited to have you! Thimble is developed by people from all over the world, some just learning to program and others with lots of experience. It's fun and a great way to learn about and advance the open web.

Read through this quick guide for some basic tips. They will help your first contribution go more smoothly. You can also read this blog post for a walkthrough of fixing a bug.

Table of Contents

Found a bug? File an issue

One of the important ways in which you can contribute to Thimble is by filing bug reports when you run into any issues using Thimble.

Guidelines

  • Write a descriptive issue title
    • Bad - Editor is broken
    • Good - Editor is not responsive after publishing a project
  • Provide a thorough description of the problem
    • What browser and OS are you using?
    • Does the problem happen all of the time?
  • Write out a series of steps for reproducing the bug, for example...
    • Step 1) Create a new project
    • Step 2) Add a second HTML file named "broken.html"
    • Step 3) The editor stops responding at this point
  • If possible, include a screenshot of what you are seeing
  • Check the console in your browser's developer tools
    • If you see any red errors, incliude a screenshot of those as well

Working on your first Issue

Get to know both repositories

Thimble it made up of two parts, each with a separate repository. The Thimble repo has the homepage as well as all of the UI above the actual editor windows. The Brackets repo (aka, 'Bramble' or 'BRAckets in thiMBLE') contains the editor. We separate the two apps for security reasons, since our Brackets editor allows users to write and then execute random JavaScript. By hosting these from different origins, we isolate them and keep everything secure. It makes development a bit harder, but keeps our users safe.

Go ahead and check them out, the README.md file in each repo contains the instructions on how to get your local development environment up and running.

Find a good first issue

Now that you've got your environment up and running, look through the issues in each repo to find a good starter issue. We've used the Good First Bug label to indicate which issues are a good place to start. Have a look...

Claim the issue for yourself

Once you've found a bug that you are interested in working on...

  • Scan over the issue comments and check the Assignees section on the right-hand side to make sure someone isn't already working on the issue
  • Leave a comment indicating that you want to work on the issue
    • We'll assign you and add a Assigned to Contributor label
    • This lets everyone know the issue is being worked on and someone won't take it on at the same time
  • Take one issue at a time
  • If someone has claimed an issue but it seems like they've stopped working on it, leave a comment asking them if it's okay to take over the work
  • If you decide to stop working on the issue you took, let us know in the issue

Work on your issue

When you begin working to solve the issue in your local environment, do the work in a new branch that references the issue number or problem that you are solving.

  • Before you begin, make sure you can reproduce the problem in the issue (if it's a bug) or that you understand the requirements (if it's a new feature).
    • Ask lots of questions in the issue if you're unsure
  • Create a new branch for your work based on the latest version of the master branch
    • Give your branch a descriptive name like remix-button-not-showing
  • If your work is taking more than a few days, drop a comment in the original issue to let everyone know your progress

Keep "tabs" on your indentation 🥁

Many first-time contributors run into problems when indenting the code, often mixing spaces and tabs. Our general convention to use spaces. A good guideline is to follow the conventions of the code that you are editing.

In your editor

  • There is a setting like Show Invisible Characters. Turn it on and you'll be able to see the difference between tab and space characters.
  • You can pick the type of tab you want to use: choose Spaces

Here's the difference between tabs and spaces

Also make sure the last line of the files you are working on ends with a line-break.

Get help

You'll probably need when working on your issue, and there are a few ways to do that. You can...

Submit a Pull Request

Once you've got a solution (or a good start) to the issue in your local environment, you'll want to make a Pull Request so that we can look at your code and eventually merge it in. Here are some guidelines...

  • Make the Pull Request against the master branch
  • Give the Pull Request a descriptive title
    • Good - Fixing Remix Button Not Showing - Issue 1332
    • Bad - Issue 1332
  • In the description
    • Describe the problem you are solving
    • Describe how the person reviewing your Pull Request can get your solution to work
  • Include a Fixes #1332 message in the Pull Request description
    • When the Pull Request is merged, this automatically closes the associated issue
  • Review the Files Changed tab in the Pull Request viewer to make sure only the changes you intended have made it in to the Pull Request
  • Ping someone in a comment and ask for a Review

Check if your Pull Request is good to go

At the bottom of the Conversation tab of the Pull Request page, there is a box that describes three different aspects of your Pull Request

  • Requested Changes
    • This will indicate if other members of the team have requested any changes to the code you've made.
  • Travis Tests
    • Travis is an automated system that checks your code to make sure it's valid.
    • If there are errors, click on the Details link and scroll through the Travis output to find the problem.
  • Merge conflicts
    • Sometimes, if enough time has passed since you first created your branch, changes to the master branch may require you to rebase your branch to the latest master.

If any of the three above require you to make changes you do not need to make a new Pull Request. Simply make the changes in your local branch and then push the changes up to your remote repository. Your new changes will automatically be reflected in your Pull Request.