Contributing

  • page
contributing  

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:

  • 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

Here are links to GitHub searches for those terms:

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 & 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.

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:

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.

Building the documentation

The main DoneJS repo contains DoneJS.com.

To build the site, run:

npm run document

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.

Style guide

Where possible, our code generally follows jQuery’s coding conventions.

Updating tests

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.

Updating the documentation

The docs and guides directories 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:

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.

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-pages branch.

First, from within your local DoneJS repository, create a new clone in the site folder and install the dependencies:

git clone git@github.com:donejs/donejs.git -b gh-pages site/
npm install

If you get an error saying Permission denied (publickey) then you should follow GitHub’s instructions on generating an SSH key.

Push a new commit to the gh-pages branch with the built docs:

npm run document
cd site/
git add --all
git commit -am "Updating the site"
git push origin gh-pages

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.

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!