Skip to content

How to Hack on Brackets

Jump to bottom Edit New page
Peter Flynn edited this page May 16, 2013 · 65 revisions

This page is mainly about modifying core Brackets code. If you're adding a new feature, consider [writing an extension](How to write extensions) instead.

If you're interested in submitting a pull request, review the guidelines for contributing code. Most importantly:

  1. Discuss any major changes or questions beforehand in the brackets-dev newsgroup.
  2. Follow the Pull Request Checklist to ensure a good-quality pull request.
  3. Sign the Brackets Contributor License Agreement (CLA) - we can't merge your code otherwise. You only need to do this once.

TL;DR Overview

Requirements

NOTE: All commands should be run in a Terminal window (on the Mac) or Git Bash shell (on Windows).

Setting up your dev environment

For hacking on the core Brackets HTML/CSS/JavaScript files:

  1. Fork the brackets repo
  2. Clone your fork of the repo: git clone https://github.com/<username>/brackets.git
  3. Update submodules: cd brackets && git submodule update --init
  4. Add an upstream remote: git remote add upstream https://github.com/adobe/brackets.git
  5. Run setup_for_hacking script:
mac
---
tools/setup_for_hacking.sh "/Applications/Brackets Sprint 24.app"

windows
-------
IMPORTANT! This command MUST be run in a Command Prompt started with "Run as Administrator"
tools\setup_for_hacking.bat "C:\Program Files (x86)\Brackets Sprint 24"

Optional: For hacking on the native code, see "Hacking on brackets-shell" below.

For more in-depth instructions see "Getting a Copy of the Code" below.

Hacking

  1. Make sure your local copy of source is up to date: git fetch upstream && git merge upstream/master
  2. Make sure submodules are up to date: git submodule update --init
  3. Create a feature/bugfix branch: git checkout -b <branchname>
  4. Hack!
  5. Commit your changes: git commit -am"Your commit message here"
  6. Run unit tests

Submit pull request

  1. Push changes to your fork of the repo: git push origin <branchname>
  2. Make sure you've reviewed the Pull Request Checklist and signed the Contributor Licence Agreement (CLA).
  3. Submit pull request from GitHub. If this is a bugfix, include "Fix #1234" (changing "1234" to the actual bug number) in the description. This tags the pull request in the bug comments.

Getting Started

How Brackets is Organized

Brackets is primarily built in HTML/JS/CSS, but it currently runs as a desktop app inside a thin native app shell called brackets-shell, based on CEF, that lets it access local files. (It doesn't run in the browser yet, but we're hoping to work on an in-browser version soon.)

The HTML/JS/CSS files are installed along with brackets-shell, but you can set up a separate development copy of these files and then load them in brackets-shell instead of the default installed copy. See Running Your Copy of the Code for more details.

For details on working with Brackets's architecture and APIs, see Brackets Development How-Tos.

What should I hack on?

Whatever you want, of course! Check out the CONTRIBUTING guide for some ideas.

If you're planning to do something other than a small bugfix, please start a discussion on the brackets-dev Google group or the #brackets IRC channel on freenode to get feedback. There might already be some prior thinking on what you're working on, or some reason that it hasn't already been done. We don't want you to do tons of work and then have to rewrite half of it.

What's the process?

First, sign the Brackets Contributor License Agreement (CLA). This is for your protection as well as that of the Brackets project.

Then, just submit changes as pull requests from your own fork of brackets or brackets-shell. The core dev team works in 2.5-week sprints (weird length, but it works for us). We'll try to review small pull requests quickly in the current sprint. Larger submissions may take longer - but discussing them in advance will smooth the process!

Before you submit your pull request, please make sure it's merged with master and fully tested as described in the Pull Request Checklist.

Read more on how pull requests are reviewed...

Getting a Copy of the Code

Note: Don't use the GitHub "ZIP" to get a copy of the source. The auto-generated ZIP file will be missing important dependencies.

New to git? If all this git stuff seems scary, check out GitHub's git tutorial or the Pro Git book.

The first step is to fork the repo on GitHub so you can start making changes in your local repository. For the HTML/JS/CSS code that comprises the bulk of Brackets, you only need to fork the brackets repo. (See "Hacking on brackets-shell" below if you want to work on the native code as well). To fork a repo, simply click the "Fork" button at the top of the page.

Next pull the repositories down to your local machine.

git clone https://github.com/<your username>/brackets.git
git submodule update --init

Don't skip the second line! Brackets uses submodules for third-party dependencies (like CodeMirror), so it won't work until you run this command to set them up.

You may also need to run git submodule update when you switch branches or pull from upstream, since submodule changes aren't update automatically. If you see third-party code showing up as modified in git status (something like M src/thirdparty/CodeMirror2), then you need to run this command.

Running Your Copy of the Code

If you're only hacking on HTML/JS/CSS files, you can have the installed Brackets shell run your local copy of the HTML/JS/CSS code (instead of the default installed copy) by running the tools/setup_for_hacking script. Here's how:

  1. Download and install the latest Brackets sprint build.
  2. Follow "Getting a Copy of the Code" above to fork & clone the brackets repo.
  3. On a Mac:
  4. Open a Terminal window
  5. cd to the root of your brackets repo
  6. run tools/setup_for_hacking.sh, passing the full pathname to your installed Brackets.app. For example:
tools/setup_for_hacking.sh "/Applications/Brackets Sprint 23.app"
  1. On Windows:
  2. Open a Command Prompt using "Run as Administrator"
  3. cd to the root of your brackets repo
  4. run tools\setup_for_hacking.bat, passing the full path of the directory where Brackets.exe is installed. For example:
tools\setup_for_hacking.bat "C:\Program Files (x86)\Brackets Sprint 23"
  1. Launch the installed copy of Brackets, select Help > About, and verify that the version number says "sprint xx development build" instead of "sprint xx experimental build". This indicates that you're running Brackets from your git repo instead of the installed build.

You can revert back to running the installed version of the Brackets source at any time by running tools/restore_installed_build.sh (Mac) or tools\restore_installed_build.bat (Windows) from your Brackets repo.

Getting Updates from the Main Repository

It's important to keep up to date with the main Brackets repository to make sure your pull requests match the latest Brackets builds. First you'll first need to link your local clone of Brackets to track the main Brackets repository on GitHub. Run this command from the brackets directory:

cd brackets
git remote add upstream https://github.com/adobe/brackets.git

Your repo will now have two "remotes": origin refers to your fork on GitHub, while upstream refers to the original, official Brackets repo.

If you want to avoid getting branches other than master, you can add the --track master argument after add. However, that will mean that if you need to pull a different branch, you'll need to explicitly fetch it.

If you also forked the brackets-shell repository, repeat this command for brackets-shell.

Getting the latest changes

Getting the latest changes on the Brackets master branch is a two-step process. First:

git fetch upstream

This brings down any new commits into your repo, but doesn't actually update any of your branches. Next, update your current local branch:

git merge upstream/master

This merges any changes from the main Brackets repository into whichever branch you currently have checked out locally. (To update multiple local branches, you'll need to git checkout each one in turn and repeat the merge command).

You may also need to run git submodule update at this point - if the output of git fetch said "Fetching submodule" or if git status shows an unexpected diff in a third-party library.

Rarely, an entire new submodule is added to Brackets. You'll need to run git submodule update --init when that happens.

What changes did I get?

You can see a diff before merging with git difftool ...upstream/master.

For a higher-level overview (with API important changes called out), check the Release notes after each sprint.

Contributing Code

Useful Tools for Development

If you use Brackets to edit Brackets, you can quickly reload the app itself by choosing Debug > Reload Brackets from the in-app menu. (If your Brackets gets really hosed, you may need to restart the application).

To bring up the Chrome Developer Tools on the Brackets window, use Debug > Show Developer Tools. This will open a new Chrome tab with the developer tools.

If you need to debug startup code, you can launch Brackets, open the developer tools, set your breakpoints, and then select Debug > Reload Brackets. This will re-run all of the startup code and stop at any breakpoints you have set.

You can open a second Brackets window from Debug > New Window. This is nice because it means you can use a stable Brackets in one window to edit your code, and then reload the app in the second window to see if your changes worked. You can bring up the developer tools on the second window, too.

You can use Debug > Run Tests to run our unit test suite, and Debug > Show Perf Data to show some rudimentary performance info. There is also an article on Debugging Test Windows in Unit Tests.

Modifying the Code

So you have found an issue that you want to fix or a feature you want to implement. Start off by creating a new branch in your local directory. This assumes you are working in the brackets directory, but the same thing would apply for the brackets-app project as well.

Make sure to follow the [coding conventions](Brackets Coding Conventions) for Brackets so that your code matches the rest of the project.

Start by creating a new branch off of master for the feature you want to work on. This makes sure that your master branch can stay in sync with the main Brackets repository and if the feature doesn't work or breaks something, you can always start fresh with your local master branch. It also makes updating your pull request much easier as you can see below.

git checkout master
git branch mynewfeature
git checkout mynewfeature

Note, that if you are fixing a particular issue, it can be useful to include the issue number in the branch name, for example fix_issue_68.

That creates a new branch called mynewfeature and sets it as your working branch. Any changes you make now will be linked to that branch. If you're working on a big feature that may take some time, remember that you can always use the git fetch and merge commands from upstream, as described above, to merge the latest master from the main Brackets repository into your current working branch. Dealing with merges incrementally like this can be better than trying to reconcile everything once you're finished with your feature.

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. You can use git add <filename> to add any files you've changed to the commit you want to make and then use git commit -m "COMMIT MESSAGE" to commit those changes. You can also use git commit -a to commit all of the current changes. Be sure to replace COMMIT MESSAGE with a detailed message that describes the changes you're making for that specific commit.

Once that's done the next step is to push those changes to your GitHub account using git push. This is where it's important to understand branches, origins, and remotes. You've made all of these changes (and committed them) to your local copy of the Brackets repository. And hopefully you've been pulling down new versions from the linked, remote branch of Brackets, and merging them as you go. What you need to do now is tell Github about your branch and the commits it contains. Github repositories use origin to reference your Github-hosted fork. So to push your changes use.

git push origin mynewfeature

That command creates a branch on your Github-hosted fork of Brackets and commits all of the changes. Until now everything we did was local. Now Github knows about our branch as well as our changes.

Before you submit a pull request you should make sure everything passes JSLint. This is easy because Brackets will show you anywhere in your file that JSLint sees an error. You also need to make sure that the unit tests pass without any errors. You can run the Brackets unit tests by going to Debug > Run Unit Tests in Brackets. The tests require Chrome and you should quit Chrome before running the tests for the most accurate results. Please also review the Pull Request Checklist for additional guidance.

Submitting a Pull Request

Now you're ready to submit a pull request. Go to the GitHub page for your fork of Brackets. In order to submit a pull request, you need to be looking at the branch you created, which we called mynewfeature. GitHub has a pulldown that lets you select branches in your fork of the repository. Click that, find the branch you were working on, and select it. Now you're looking at the code for that branch.

Click the pull request button in the top right and you'll be brought to a page that describes the pull request. You want to make sure that you're submitting your pull request to the adobe/brackets repository and that the pull request is coming from the branch you've been working on.

You'll be able to take a look at all of the commits associated with this pull request and all the files that you've modified. Make sure this is all correct and then in the description provide a detailed description of what your pull request does.

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.

Updating an Existing Pull Request

In a lot of cases you may have to make changes to your pull request. If you're working off a branch, Github makes this very easy. After you've gotten comments on the pull request and know what changes you need to make, go into your code and make sure you're working on your branch.

git checkout mynewfeature

Then go through the steps above to modify your code and make any changes based on comments from the pull request. Commit all of those changes with git commit and then push the changes to your Github-hosted fork with git push origin mynewfeature.

As soon as you push those changes to the origin, the pull request you submitted will automatically be updated with the new code. If you go look at the pull request, you'll see a new comment entry with the commits that you added to the branch. Sometimes it helps to add another comment right after that commit describing some of the changes you made in more detail.

Fixing a Bug

If you are working on a specific bug, here are the steps to follow:

  1. Create a new branch and use the issue number as the branch name. Be sure you have the latest code from the main repository before branching to make merging as easy as possible (instructions above).
  2. Fix the bug.
  3. Commit and push your changes according to the instructions above.
  4. Submit a pull request. Make sure the text "issue #123" (use your specific issue number) is in the pull request notes in order to create a link to the issue.

That's it! You've just made Brackets even better.

Hacking on brackets-shell

For most of your changes to Brackets, you should only need to edit the HTML/JS/CSS code in the brackets repo. You won't need the source for brackets-shell because you can use a pre-built binary from a Brackets installer to run your modified HTML/JS/CSS code (see instructions above).

However, you may want to set up a dev environment for brackets-shell if:

  • You want to hack on the native code.
  • You want to pull the latest from the brackets repo master and it requires a new brackets-shell build that hasn't been released as a binary yet. (This is uncommon, but it can happen).
  1. Similar to the steps above, fork the bracket-shell repo and git clone it.
  2. Follow the build instructions on the brackets-shell wiki.
Add a custom footer
Add a custom sidebar

Clone this wiki locally