Skip to content

Contributing to Brackets

ryanstewart edited this page Apr 28, 2012 · 26 revisions

How to Get Started

The first step is to find something to fix. [How to Hack on Brackets] (wiki/How-to-Hack-on-Brackets) has some good pointers for finding issues and getting your head around how to get up to speed with Brackets.

The first step is to fork the projects so you can start making changes in your local repository. Fork both brackets-app and brackets.

Next pull both of those repositories down to your local machine. Your folder structure should have the brackets project within brackets-app.

git clone git@github.com:<your username>/brackets-app.git
cd brackets-app
git clone git@github.com:<your username>/brackets.git

Because Brackets relies on CodeMirror you want to make sure you have the latest version of CodeMirror. Brackets uses submodules to help track both CodeMirror and the Brackets project from Brackets app. To make sure everything is up to date go back to your brackets-app folder and run.

git submodule update --init --recursive

That should both get the latest version of CodeMirror and sync your fork of Brackets with brackets-app. If you run bin/mac/Brackets.app or bin/win/Brackets.exe you'll have your just-forked version of Brackets up and running.

Tracking Changes

Brackets development moves pretty quickly so I've found that it's really handy to be able to always track the changes from the main branch and pull them down to my local fork. To link your local fork of brackets-app with the main project, in your brackets-app directory type

git remote add --track master upstream git@github.com:adobe/brackets-app.git

Then do the same for the Brackets project

cd brackets
git remote add --track master upstream git@github.com:adobe/brackets.git

Any time you want to get the latest changes from the main repo you can use

git fetch upstream master

That won't merge changes, but it will grab them. You can merge the changes into your local fork with

git merge upstream/master

You'll have to do this for both the brackets-app project and the brackets project. I also find it helpful to run

git submodule update --init --recursive

again in the brackets-app directory to get any changes from CodeMirror.

Making Changes

So you've got an issue you want to fix. Start off by creating a new branch in your local directory. This assumes you're working in the brackets directory, but the same thing would apply for the brackets-app project as well.

Start by creating a new branch so that you can always be sure master doesn't get messed up.

git branch mynewfeature

That creates a new branch called mynewfeature. Any changes you make now will be linked to that branch. Go ahead and modify some code, make your fix, and be sure that it works in your copy of Brackets. Once you're happy with the fix, it's time to commit those changes and get ready to send it back to the team. If you're adding new files you'll have to run git add but if you're just modifiying existing files you can run

git commit -a

That will bring up a vi terminal where you should provide a description for what changes you just made. Once that's done the next step is to push those changes to your Github account using git push.

git push origin mynewfeature

That sends the branch (and the commits) to your Github-hosted fork of the project. Until now everything we did was local. Now Github knows about our branch as well as our changes.

Submitting a Pull Request

Now you're ready to submit a pull request. Go to the Github page for your fork of Brackets. If everything is working correctly, Github will actually detect that you pushed a branch and will show you a Pull request button. Click that button and you'll be brought to the pull request page where you can see the commits, look at the file differences, and add some comments. Use the comment box to explain in more detail your changes, why you made them, and any specific issues you're fixing. Then send it to the team.

Now you've got your first pull request in! Check back for comments the team might have for the pull request. If it's set, they'll merge it in and you're officially a Brackets contributor. Sometimes they'll ask you to make changes.

Making Changes to an Existing Pull Request

Clone this wiki locally