Thanks for thinking about helping! How would you like to help?
- I want to build a new feature.
- I want to improve the documentation.
- I want to fix a bug.
- I want to refactor some code.
- I want to update dependencies
- I don't know how to help.
Also, check out our workflow and recommended tools.
-
Read and work through the installation guide.
-
Run the tests. We only take pull requests with passing tests, and it's great to know that you have a clean slate:
ember exam. More information on testing commands can be found here
Okay, you're ready to go!
If there's already an issue for the feature you want to tackle, how complete is the description? Do you know what to do next? Are you confident you know what "done" looks like?
If there's not an issue yet, write one.
Whether you're writing a new issue or improving on an existing issue, be sure to clarify exactly how you expect the finished change to look and work.
One of the best ways to write a feature is in user story format:
As an [actor], I want to do [action], so that [benefit].
For example, let's say we wanted to write some Slack integration for new comments posted to a Code Corps project. That user story might look something like:
As a project maintainer, I want to see new comments on my project task in my Slack channel so that everyone can see and react to some of the latest changes in the project.
You may want to go deeper into detail. Posting screenshots of designs or expected test cases and scenarios are even more helpful. Place yourself in the shoes of the person who's going to accomplish the task – even if that person is you. What steps should I be taking next to finish this task?
Once you've created the issue, you can make your changes and push them up.
New to git? Check out Using Git effectively.
You can see how much code is documented on Inch CI.
We use YUIDoc to document our code.
You can learn about how to write documentation with YUIDoc from these places:
- Our style guide
- YUIDoc's syntax guide
If you're just looking to improve the README, there's a couple things you should know:
- Open an issue first. It's better if we discuss your proposed changes.
- We try to keep the main
README.mdlightweight and use it as a jumping point to other docs. - Most other docs can be placed in
/docs. - Try to make it easy for people to jump around in your doc.
If you're fixing a bug that's already been added to the issues, ask yourself whether the bug description is clear. Do you know what circumstances led to the bug? Does it seem easy to reproduce?
If you've spotted a bug yourself, open an issue and try to answer those questions.
Then start writing some code:
- Make the tests fail.
Identify what's happening in the bug with a test. This way the bug is reproducible for everyone else in the project, and we won't regress into making the bug ever again (hopefully!).
- Make the tests pass again.
Write your code that fixes the bug and makes it pass.
Refactoring code shouldn't require any new tests, but you should make sure the tests still pass.
Greenkeeper keeps track of dependencies for us and submits pull requests when a dependency is updated. To update a depencency, you will need to follow these steps:
-
The pull request will contain useful information about what's changed, including breaking changes. You will also want to check the dependency's github and/or npm listing for changelog and recommended updating steps.
-
Pull down the branch locally.
-
Update the dependency and perform any steps the project suggests for updating. Sometimes this requires updating other dependencies, changing configuration code, or other tasks.
-
Build, run, and verify that tests pass.
-
Verify that everything looks good: Check pages and components that make use of the library and ensure they are still working as expected.
At this point, follow the steps described in I finished my changes, but you won't need to open a pull request since one already exists. Mark the pull request as needs code review.
When you're ready to write some new code, you should do the following:
- Write some documentation for your change.
Why do this first? Well, if you know the behavior you want to see, then it's easier to validate if it works as expected. Think of this as documentation-driven development.
What kind of documentation are you writing?
-
Add a test for your change. Here's how to run tests.
-
Make the test pass.
Try to keep your changes to a max of around 200 lines of code whenever possible. Why do this? Apparently the more changes incurred in a pull request, the likelier it is that people who review your code will just gloss over the details. Smaller pull requests get more comments and feedback than larger ones. Crazy, right?
Done with your changes and ready for a review?
Not a problem! You can try looking around for issues that say good for new contributors. Documentation really is a good place to start. If you're still not sure, just join our Slack and flag someone down. Someone can help point you in the right direction.
Now you just need to push your finished code to your fork and submit a pull request.
Your pull request will be run through a continuous integration server to test your changes, as described here.
At this point you're waiting on us. We like to at least comment on, if not accept, pull requests within a week's time. We may suggest some changes or improvements or alternatives.
Some things that will increase the chance that your pull request is accepted:
- Use Ember.js idioms
- Include tests that fail without your code, and pass with it
- Update the documentation, the surrounding one, examples elsewhere, guides, whatever is affected by your contribution
Has your code been reviewed? Here's what we need before we can merge.
We use CircleCI to test your branches and continuously deploy branches merged into develop to our staging API and branches merged into master to our production API.
If your test fails on Circle, you should re-check your tests. Sometimes this indicates a mismatch between your environment and our expected environment.
The circle.yml file specifies what happens in the builds. You can read more about that in Circle's documentation.
The CircleCI builds also rely on some environment variables for reporting, deployments, and other requirements.
If you've had a pull request reviewed and accepted, congratulations! Before we can merge your changes, we'll need you to rebase off origin/develop and squash your commits into one. This will give us a cleaner git history.
Never done this before? No problem. We'll walk you through it in our guide, and you can read a deeper guide about rewriting history to understand more.
When making code changes with Git, it is best to develop a workflow. Every 'feature', which can be anything from a 1-line change to an entire component, should be done on a seperate feature branch.
Let's say you are working on issue 6000, which requests that the needs_coffee property of programmer be changed to a constant that always returns true. You'll make the following steps:
- Check out the code, or fetch any updates from github.
- Assign yourself the issue (if you aren't a contributor yet, comment that you are working on it)
- Create a new feature branch:
git branch <feature-name>For the <feature-name>, use our naming standard: [issue#]-[adds|removes|updates]-[description]
So, for the issue you just assigned yourself, the feature name would be 6000-updates-programmer-coffee-property. In most cases, adds, removes, and updates will suffice. If none of those options make sense use another present-tense verb. The description component of the feature name should also be in present-tense. Note the use of hyphens (-) to seperate all words.
- Checkout your feature branch:
git checkout <your-feature-branch>- Make your changes and push commits to your feature branch often
- Once you've finished, make a pull request.
To learn more about this workflow, check out GitHub Flow.
GitHub has released a tool that can aid working with GitHub via the command line. Check it out! It's called hub and it makes cloning repositories and making pull requests a breeze.
Bash user? Check out bash git completion which adds helpful information to your prompt about which branch you are currently in, adds tab completion of git commands, and gives you helpful status information on your files.
If you are a Windows user, you should really be using Powershell as your command line (especially since it adopts bash aliases for most cmd.exe functions).
Install posh-git which, like bash git completion, provides tab completion and helpful repository info in your prompt.
You'll probably want to keep some sort of Bash emulator on hand. Git comes with it's own bash shell, but its not very good. Fortunately there are a few other great options:
- ConEmu is a fantastic console emulator that comes with two bash options.
- Cmder is ConEmu on steroids with Monokai console coloring and git bash completion, Posh-git, and oh-my-posh already installed
- Windows Subsystem for Linux More complex to use, but it gives you a full bash shell in an Ubuntu enviornment.