-
Notifications
You must be signed in to change notification settings - Fork 1
Contributing to Meteor
We are excited to have your help building Meteor — both the platform and the community behind it — and share in the rewards of getting in early on something great. Here's how you can help with bug reports and new code.
We welcome clear bug reports. If you've found a bug in Meteor that isn't a security risk, please file a report in our issue tracker.
There is a separate procedure for security-related issues. If the issue you've found contains sensitive information or raises a security concern, email
security@meteor.cominstead, which will page the security team.
Please don't use GitHub issues for feature requests or proposals. Most additions deserve a fair bit of discussion, which doesn't work super well inside a GitHub issue. Read on for how to get changes into Meteor.
A Meteor app has many moving parts, and it's often difficult to reproduce a bug based on just a few lines of code. So your report should include a reproduction recipe. By making it as easy as possible for others to reproduce your bug, you make it easier for your bug to be fixed. We may not be able to tackle an issue opened without a reproduction recipe. If we can't, we'll close them it a pointer to this wiki section and a request for more information.
A single code snippet is not a reproduction recipe.
A reproduction recipe works like this:
-
Create a new Meteor app that displays the bug with as little code as possible. Try to delete any code that is unrelated to the precise bug you're reporting, including extraneous Atmosphere packages.
-
Create a new GitHub repository with a name like
meteor-reactivity-bug(or if you're adding a new reproduction recipe to an existing issue,meteor-issue-321) and push your code to it. (Make sure to include the.meteor/packagesand.meteor/releasefiles!) -
Reproduce the bug from scratch, starting with a
git clonecommand. Copy and paste the entire command-line input and output, starting with thegit clonecommand, into the issue description of a new GitHub issue. Also describe any web browser interaction you need to do. -
If you reproduced the issue using a checkout of Meteor instead of using a released version that was pinned with a
.meteor/releasefile, specify what commit in the Meteor repository was checked out.
If you want to submit a pull request that fixes your bug, that's even better. We love getting bugfix pull requests. Just make sure they're written to the MDG style guide and come with tests. Read further down for more details on proposing changes to core code.
If you have an idea for something new in Meteor, usually the best option is to publish it as an Atmosphere package. We want to keep the 1.0 core as small as possible, with just the parts that most apps will need. If there's a way to do something as an Atmosphere package, we'll steer you in that direction.
Publishing your code as a separate package decouples your change from
Meteor's core release cycle so you can maintain the code independently.
It gives you and others in the community freedom to explore different
variations of your idea. And it lets developers "vote with their feet"
to find the best way to solve a problem or add a capability. For
example, the popular
iron-router package is
an evolution of two earlier routing solutions that were both already
available in Atmosphere.
We will be folding direct support for Atmosphere packages into Meteor before 1.0. After that, you won't need the separate
mrttool to use or publish them, and updating your application's Meteor release will automatically update each package to its correct version.
For historical reasons, some packages that really ought to be in
Atmosphere are currently in core, like less, coffeescript, and d3.
We welcome PRs against these packages but they may not get the highest
priority. We'll probably bump the versions of some of these packages
before 1.0, but 90% of the work with these packages is QAing the new
release, verifying the software licenses, and so on; not the code diff.
Looking ahead to the day when we can include popular community packages in the default application stack, it's probably a good idea to write your packages to the MDG style guide. You can read more about that in the next section. In particular, two things you can get a head start on are:
-
Your package should have tests. See the
iron-routertest suite as an example. -
Meteor minifies all JS/CSS. Packages should include only the original JS/CSS files, not the minified versions.
Eventually you may want to change something in a core Meteor package, or
in the meteor command line tool. These changes have the highest
standards for API design, for the names of symbols, for documentation,
and for the code itself. Be prepared for a lot of work!
It may take some study to get comfortable with Meteor's core
architecture. Each core package is designed to stand separately. At
the same time, all the parts of core fit together to make the
distinctive Meteor development experience. Core APIs should be consistent between
the client and the server (not always workable; we don't have fibers on
the client or a DOM on the server). We prefer synchronous APIs wherever possible: you can use Meteor._wrapAsync on the server to wrap async APIs that take a callback.
Above all, we are concerned with two design requirements when evaluating any change to a core package:
-
Nothing in Meteor should harm the experience of a new Meteor developer. That can be a difficult standard to reach, because we're concerned here with the entire experience of developing and deploying an application. For example, we work hard to make sure that the Meteor docs don't force new users to understand advanced concepts before they need them. And we think a great deal about making our APIs as intuitive as possible, so that you can figure out a lot of Meteor without first having a long reading session with the docs.
-
Nothing in Meteor should preclude an expert from doing what they want. The low-level DDP API maps closely to the DDP wire protocol, for example, so that when the need arises you can control exactly what data gets sent to a client. It's okay to write syntactic sugar that makes the easy stuff easy, but if your change harms the experience of an expert then we'll probably prefer a different approach.
We have found that writing software to meet both these standards at the same time is hard but incredibly rewarding. We hope you come to feel the same way.
You'll have the best chance of getting a change into core if you can
build consensus in the community for it and eventually get a core
developer on board. It is very unlikely that we'll take a patch that adds a feature
without seeing some initial discussion about it. Probably the best way
to get consensus is to join the meteor-core mailing list, search the
archives for anything relevant, and then post your proposal there. It's
okay to post an idea to meteor-core without having a design or some
initial code — others may be interested in helping.
Another option is to come to Devshop in San Francisco, where you can sit with a core developer and work out some of the design in person.
Most non-trivial changes need more discussion than comfortably fits
inside GitHub's issue tracker, so that is not a good place to propose a
new idea. We will probably close most "surprise" PRs that we find there
with a note to start a discussion on meteor-core.
Small changes, especially if they don't affect APIs or documentation,
may not really need a thread on meteor-core first. But a new feature
that's small enough not to need discussion probably isn't super
valuable. It may not get the highest priority from the core team, or we
may just close it.
During the runup to 1.0, we are going to focus on buttoning up the remaining big ticket items and closing bugs. We'll probably have to defer some good ideas and smaller, uncontroversial changes until after 1.0 is out.
Once you've hammered out a good design and gotten at least one core developer on board, go ahead and submit a pull request. Please follow these guidelines:
-
Sign the contributor's agreement.
-
Base all your work off of the devel branch. The devel branch is where active development happens. We do not merge patches directly into master.
-
Name your branch to match the feature/bug fix that you are submitting.
-
Limit yourself to one feature or bug fix per pull request.
-
Include tests that prove your code works.
-
Follow the MDG style guide for code and commit messages.
-
Be sure your author field in git is properly filled out with your full name and email address so we can credit you.