Labs/Bespin/Contributing

Contributing to Bespin

Thanks for showing an interest in Bespin. There is lots to do, so it's great to have lots of smart contributors. There are many types of help too. From filing bugs to writing docs to helping on our mailing list or by of course writing code!

What are you interested in today?

• Labs/Bespin/Testing Testing
• Writing Code (right below)
• Writing Docs (at the end of this page)

Contributing Code

You'll need to start by Labs/Bespin/DeveloperGuide/Setup getting Bespin set up. The Bespin source is stored in a Mercurial repository. If you're new to 'HG', you should start here, or checkout the Wikipedia page or Red-Bean book.

It probably makes sense to discuss what you're thinking of working on, on the core mailing list or on IRC. And, if you're stuck for ideas, you could try looking in Bugzilla.

Writing good code

• Try to make sure as little code as possible is loaded, which means that you should make extensive use of the plugin system
• Try to make sure that code is very much asynchronous and never synchronous
• Test to see if it makes sense to offload long running code to a Worker (may not be the right thing to do!)
• Have a setting option that allows people to turn off a given feature in a manner that gives no overhead

Unit Testing

For "Bespin Core" and "Bespin Supported" parts of the system, unit tests are required as much as is practical. See the unit testing section of the Developer Documentation for more information.

Sending Contributions

Since Mercurial is a distributed version control system, you've got three options for getting code changes to us:

1. Have a public hg repository of your own that you can point us to (http://bitbucket.org provides free public repositories)
2. Create a patch for your changes
3. Create a "bundle" for your changes (a bundle is a mercurial-specific format that includes every commit, rather than just a snapshot of the difference)

The recommended approach is to create a public repository (such as one on bitbucket.org) that we can pull from. In order to ensure that we can easily make use of your changes, you should put the changes on separate branches, preferably using hg bookmarks. You can learn a bit about branching and bookmarks in A Guide to Branching in Mercurial. Some specific tips:

• Separate branches would be used for unrelated bugs and features, so that we can pull one without having to pull another
• You'll have an easier time keeping a repository up to date than a patch, which is why this is the recommended approach
• Having separate branches in your repo using bookmarks is easier than having lots of separate repositories that would all need to be set up and configured
• hg bookmarks do not get pushed to the remote repository. So, when telling us that you want us to pull from you, be sure to give us the full commit ID. You can get this with hg id -r bookmarkname. Also be sure to tell us where your repository is!
• In the related bug in bugzilla, add a [needs-pull] flag to the whiteboard, so that we can easily spot that we have incoming code.

You can submit enhancements that are not part of an existing bug by opening a new bug in Bugzilla. By keeping everything in Bugzilla, we'll have an easier time getting release notes together.

Code Review

All non-trivial changes, even by Mozilla employees, to Core and Supported parts of Bespin will be reviewed by someone other than the original author of the change. The process is the same, regardless of who made the change:

1. A bug in bugzilla is marked [needs-pull] in the whiteboard by the author of the change
2. That bug is assigned to someone for review
3. The reviewer comments on the change
4. If additional work is required, the [needs-pull] flag is removed and the bug is reassigned to the original author of the patch
5. Otherwise, the change is applied to the main repository and the bug is closed. If the reviewer doesn't have access to the main repository, the [needs-pull] flag in the whiteboard is changed to [needs-commit].

Reviewers will strive to review changes as quickly as possible, and maximally within a week.

Documentation

User-level, process and design documentation are all stored in this wiki. Developer and API documentation that will likely change from release-to-release is stored in the docs/ directory in the bespinclient repository.

Committer's Agreement

Mozilla records CLAs for all committers, so for we may need you to sign a CLA. The process for Firefox is described here. This is the process that we are initially following.