Contributing to an open source project can be an intimidating experience. We’re committed to making it as pleasant and rewarding as possible. Please always feel free to reach out to us on Gitter.
Code of Conduct
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to make participation in our project and community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
Our forums and Gitter chat are the best places to ask questions. The core team regularly checks both and there are other users who generously help others.
If you’re interested in contributing to DoneJS, the core team is happy to pair with you to fix a bug or write a new feature! Please either message us on Gitter or the forums, or leave a comment on the GitHub issue you’re interested in helping with. We will happily walk you through setting up your development environment, creating a test and/or writing documentation, and submitting a pull request.
Project Organization
At its core, DoneJS is a CLI tool that generates an application structure with a number of projects that are built to work together.
DoneJS uses GitHub Issues to track bugs. As noted above, DoneJS is made up of many individual GitHub repositories. Ideally, bugs are created within the
repository whose code is causing the issue. For example, if you’re having issues with the development server, you can create an issue at donejs/done-serve/issues/new.
If you do not know which repository your issue belongs to, that’s okay! Please
create your issue in
the main DoneJS repo. The core team will
move the issue to the correct repository (if necessary).
When creating an issue, it’s helpful to include:
How often you can reproduce it.
A detailed description of the issue with specific details to help us understand the problem.
A list of the steps to reproduce the issue.
What actually happened versus what you expected to have happen.
Details about your environment, including the version of DoneJS, Node.js, and npm you’re using.
Before filing a new issue, please search for previous tickets. If there’s something similar, add to that, or
give it a 👍. If you can provide additional information that’s not already in the issue, please add a comment to it.
If you are unsure about any of this or have any other questions, please reach out to
us on the DoneJS forums or talk to us on
the Gitter donejs/donejs channel. We’re happy to discuss any bugs and help you file a bug report.
Suggesting Features
DoneJS uses GitHub Issues to track feature suggestions. As noted above, DoneJS is made up of many individual GitHub repositories. Ideally, feature suggestions are created within the
repository whose code could be improved. For example, if you have a suggestion related to the development server, you can create an issue at donejs/done-serve/issues/new.
If you do not know which repository your issue belongs to, that’s okay! Please
create your issue in
the main DoneJS repo. The core team will
move the issue to the correct repository (if necessary).
When filing a feature suggestion, it’s very helpful to include:
Examples of what using the feature will look like.
Benefits and drawbacks of the feature.
Why the feature is important.
Any implementation details around the feature.
Before filing a new suggestion, please search for previous feature requests. If there’s something similar, add to that, or
give it a 👍. If you have additional ideas that are not already in the issue, please add a comment to it.
If you are unsure about any of this or have any other questions, please reach out to
us on the DoneJS forums or talk to us on
the Gitter donejs/donejs channel. We’re happy to discuss any ideas and help you file a feature suggestion.
Finding Ways to Contribute
There are many ways to contribute to DoneJS, whether you’re a developer who wants to code, a designer who can help improve the design and usability of our projects, or someone who’s interested in helping other members of the community.
Finding open issues
DoneJS uses GitHub Issues to track improvements we want to make to the project, whether that’s bug fixes, new features, design improvements, etc.
We use a few labels to organize issues across all of the repositories:
“help wanted” for any issues with which the core team would like help
“easy” for issues the core team thinks are good for someone who’s new to contributing
“documentation” for issues related to documenting the APIs
“design” for issues that could use a designer’s expertise
“p0”, “p1”, “p2”, etc. for prioritizing issues
Here are links to GitHub searches for those terms:
This section will walk you through setting up the main DoneJS repository on your computer. Remember that DoneJS is split into multiple repositories, but you can apply the same general steps to set up any of the other repos.
Signing up for GitHub
If you don’t already have a GitHub account, you’ll need to create a new one.
Forking and cloning the repository
A “fork” is a copy of a repository in your personal GitHub account. “Cloning” is the process of getting the repository’s source code on your computer.
GitHub has a guide for forking a repo. To fork DoneJS, you can start by going to its fork page.
Next, you’ll want to clone the repo. GitHub’s cloning guide explains how to do this on Linux, Mac, or Windows.
GitHub’s guide will instruct you to clone it with a command like:
git clone https://github.com/YOUR-USERNAME/donejs
Make sure you replace YOUR-USERNAME with your GitHub username.
If you just cloned the repo from the command line, you’ll want to switch to the folder with your clone:
cd donejs
Next, install the project’s dependencies with npm:
npm install
Running the tests
Firefox is used to run the repository’s tests. If you don’t already have it, download Firefox. Mozilla has guides for installing it on Linux, Mac, and Windows.
After Firefox is installed, you can run:
npm test
If every test passed, congratulations! You have everything you need to change the code and have the core team review it.
npm run will look for the document script in the repository’s package.json and run it.
Viewing the site
After you build the docs, your donejs repository will contain a site folder with the website.
To view the site, we recommend you install http-server.
npm install http-server -g
After it’s installed, you can start a server for the site directory:
http-server site
http-server will tell you where you can go in your browser to see the site. It will be something like http://127.0.0.1:8080.
Changing the Code
Now that your computer is set up to develop DoneJS locally, you can make changes in your local repository.
The DoneJS projects generally follow the GitHub flow. This section will briefly explain how you can make changes on your computer and submit a pull request to have those changes merged into the main project.
Creating a new branch
Starting in the DoneJS repository you have cloned to your computer, you can create a new branch:
git checkout -b your-branch-name
Replace your-branch-name with the name of your feature branch. You can name the feature branch whatever you’d like. We recommend starting the name with the issue number and a few words related to the issue. For example, for #295 “Make a contribution guide”, 295-contribution-guide is an appropriate branch name.
The test directory contains files related to testing the code in the repository. When fixing bugs or writing new features, you should update the existing tests or create new tests to cover your changes.
After updating the tests, make sure you run the tests.
Once you’ve made your changes and run the tests, you can push your branch to GitHub:
git push origin your-branch-name
Make sure you replace your-branch-name with the name of your branch.
Next, go to the DoneJS repository’s compare changes page and click on “compare across forks.” You’ll need to change the “head fork” to your repository and select your branch name.
After you’ve selected your forked repository and branch, you can click on “Create pull request”. Give your PR a meaningful title and provide details about the change in the description, including a link to the issue(s) your PR addresses. If applicable, please include a screenshot or gif to demonstrate your change. This makes it easier for reviewers to verify that it works for them. LICEcap is a great tool for making gifs.
Once you’ve filled out your pull request’s details, click on “Create pull request”. The core team will receive a notification about your pull request and will provide feedback.
If you get an error saying Permission denied (publickey) then you should follow GitHub’s instructions on
generating an SSH key.
Install the dependencies, build the site, and push a new commit to the gh-pages branch with:
make
That’s it! DoneJS.com should now have your changes.
Evangelism
Hopefully you love DoneJS as much as we do and you want to share your
knowledge about it. Fantastic! We want to help you.
There are lots of ways to spread the word about DoneJS, including:
Writing a blog article
Speaking at a conference or meetup
Organizing a DoneJS meetup
No matter what you’re interested in, please email Chasen Le Hara so he can help promote you and what you’re doing.
Writing a blog article
If you’re writing something about DoneJS and would like the core team to review it,
we’re happy to help. Once it’s published, let us know so we can promote it.
Speaking at a conference or meetup
The presentations list contains a variety of talks related to the DoneJS projects.
We’re always looking for people to speak at one of these groups, become an organizer,
or start their own group. If you are interested in any of these things,
please let us know!
Thank you for your interest in contributing to DoneJS! DoneJS is maintained by the core team but depends on contributors like you! Whether you’re interested in fixing issues, answering questions, or spreading the word, we welcome you to our community!
Contributing to an open source project can be an intimidating experience. We’re committed to making it as pleasant and rewarding as possible. Please always feel free to reach out to us on Gitter.
Code of Conduct
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
Please read our Code of Conduct in its entirety before participating in our community.
Getting Help
Our forums and Gitter chat are the best places to ask questions. The core team regularly checks both and there are other users who generously help others.
If you’re interested in contributing to DoneJS, the core team is happy to pair with you to fix a bug or write a new feature! Please either message us on Gitter or the forums, or leave a comment on the GitHub issue you’re interested in helping with. We will happily walk you through setting up your development environment, creating a test and/or writing documentation, and submitting a pull request.
Project Organization
At its core, DoneJS is a CLI tool that generates an application structure with a number of projects that are built to work together.
The following projects are a core part of DoneJS:
Here are the DoneJS projects that glue things together and add additional functionality:
Reporting Bugs
DoneJS uses GitHub Issues to track bugs. As noted above, DoneJS is made up of many individual GitHub repositories. Ideally, bugs are created within the repository whose code is causing the issue. For example, if you’re having issues with the development server, you can create an issue at donejs/done-serve/issues/new.
If you do not know which repository your issue belongs to, that’s okay! Please create your issue in the main DoneJS repo. The core team will move the issue to the correct repository (if necessary).
When creating an issue, it’s helpful to include:
Before filing a new issue, please search for previous tickets. If there’s something similar, add to that, or give it a 👍. If you can provide additional information that’s not already in the issue, please add a comment to it.
If you are unsure about any of this or have any other questions, please reach out to us on the DoneJS forums or talk to us on the Gitter donejs/donejs channel. We’re happy to discuss any bugs and help you file a bug report.
Suggesting Features
DoneJS uses GitHub Issues to track feature suggestions. As noted above, DoneJS is made up of many individual GitHub repositories. Ideally, feature suggestions are created within the repository whose code could be improved. For example, if you have a suggestion related to the development server, you can create an issue at donejs/done-serve/issues/new.
If you do not know which repository your issue belongs to, that’s okay! Please create your issue in the main DoneJS repo. The core team will move the issue to the correct repository (if necessary).
When filing a feature suggestion, it’s very helpful to include:
Before filing a new suggestion, please search for previous feature requests. If there’s something similar, add to that, or give it a 👍. If you have additional ideas that are not already in the issue, please add a comment to it.
If you are unsure about any of this or have any other questions, please reach out to us on the DoneJS forums or talk to us on the Gitter donejs/donejs channel. We’re happy to discuss any ideas and help you file a feature suggestion.
Finding Ways to Contribute
There are many ways to contribute to DoneJS, whether you’re a developer who wants to code, a designer who can help improve the design and usability of our projects, or someone who’s interested in helping other members of the community.
Finding open issues
DoneJS uses GitHub Issues to track improvements we want to make to the project, whether that’s bug fixes, new features, design improvements, etc.
We use a few labels to organize issues across all of the repositories:
Here are links to GitHub searches for those terms:
Triaging issues that have no labels is also really helpful! Here are some searches you can use to find unlabeled issues:
Getting involved in the community
You can also get involved in our community by posting in our forums, chatting with us on Gitter, and answering questions on Stack Overflow.
Spreading the word
We also always need help spreading the word about the DoneJS projects. Check out the evangelism section on how you can write a blog post, speak at a conference, or organize a meetup.
Developing Locally
This section will walk you through setting up the main DoneJS repository on your computer. Remember that DoneJS is split into multiple repositories, but you can apply the same general steps to set up any of the other repos.
Signing up for GitHub
If you don’t already have a GitHub account, you’ll need to create a new one.
Forking and cloning the repository
A “fork” is a copy of a repository in your personal GitHub account. “Cloning” is the process of getting the repository’s source code on your computer.
GitHub has a guide for forking a repo. To fork DoneJS, you can start by going to its fork page.
Next, you’ll want to clone the repo. GitHub’s cloning guide explains how to do this on Linux, Mac, or Windows.
GitHub’s guide will instruct you to clone it with a command like:
Make sure you replace
YOUR-USERNAMEwith your GitHub username.Installing the dependencies
After you’ve forked & cloned the repository, you’ll need to install the project’s dependencies.
First, make sure you’ve installed Node.js and npm.
If you just cloned the repo from the command line, you’ll want to switch to the folder with your clone:
Next, install the project’s dependencies with npm:
Running the tests
Firefox is used to run the repository’s tests. If you don’t already have it, download Firefox. Mozilla has guides for installing it on Linux, Mac, and Windows.
After Firefox is installed, you can run:
If every test passed, congratulations! You have everything you need to change the code and have the core team review it.
Building the documentation
The main DoneJS repo contains DoneJS.com.
To build the site, run:
npm runwill look for thedocumentscript in the repository’spackage.jsonand run it.Viewing the site
After you build the docs, your
donejsrepository will contain asitefolder with the website.To view the site, we recommend you install http-server.
After it’s installed, you can start a server for the
sitedirectory:http-serverwill tell you where you can go in your browser to see the site. It will be something like http://127.0.0.1:8080.Changing the Code
Now that your computer is set up to develop DoneJS locally, you can make changes in your local repository.
The DoneJS projects generally follow the GitHub flow. This section will briefly explain how you can make changes on your computer and submit a pull request to have those changes merged into the main project.
Creating a new branch
Starting in the DoneJS repository you have cloned to your computer, you can create a new branch:
Replace
your-branch-namewith the name of your feature branch. You can name the feature branch whatever you’d like. We recommend starting the name with the issue number and a few words related to the issue. For example, for #295 “Make a contribution guide”,295-contribution-guideis an appropriate branch name.Style guide
Where possible, our code generally follows jQuery’s coding conventions.
Updating tests
The
testdirectory contains files related to testing the code in the repository. When fixing bugs or writing new features, you should update the existing tests or create new tests to cover your changes.After updating the tests, make sure you run the tests.
Updating the documentation
The
docsandguidesdirectories contain the files used to generate DoneJS.com.After making changes, make sure you build the documentation.
Submitting a pull request
Once you’ve made your changes and run the tests, you can push your branch to GitHub:
Make sure you replace
your-branch-namewith the name of your branch.Next, go to the DoneJS repository’s compare changes page and click on “compare across forks.” You’ll need to change the “head fork” to your repository and select your branch name.
After you’ve selected your forked repository and branch, you can click on “Create pull request”. Give your PR a meaningful title and provide details about the change in the description, including a link to the issue(s) your PR addresses. If applicable, please include a screenshot or gif to demonstrate your change. This makes it easier for reviewers to verify that it works for them. LICEcap is a great tool for making gifs.
Once you’ve filled out your pull request’s details, click on “Create pull request”. The core team will receive a notification about your pull request and will provide feedback.
GitHub has additional documentation on creating a pull request from a fork that you might find useful.
Updating DoneJS.com
DoneJS.com is hosted on GitHub pages from the
gh-pagesbranch.First, from within your local DoneJS repository, create a new clone in the
sitefolder:If you get an error saying
Permission denied (publickey)then you should follow GitHub’s instructions on generating an SSH key.Install the dependencies, build the site, and push a new commit to the
gh-pagesbranch with:That’s it! DoneJS.com should now have your changes.
Evangelism
Hopefully you love DoneJS as much as we do and you want to share your knowledge about it. Fantastic! We want to help you.
There are lots of ways to spread the word about DoneJS, including:
No matter what you’re interested in, please email Chasen Le Hara so he can help promote you and what you’re doing.
Writing a blog article
If you’re writing something about DoneJS and would like the core team to review it, we’re happy to help. Once it’s published, let us know so we can promote it.
Speaking at a conference or meetup
The presentations list contains a variety of talks related to the DoneJS projects.
Organizing a DoneJS meetup
There are several local DoneJS groups:
We’re always looking for people to speak at one of these groups, become an organizer, or start their own group. If you are interested in any of these things, please let us know!