CONTRIBUTING.md

Contributing to the Tasking Manager

Table of contents:

1. Welcome
2. How can I contribute?
3. How we structure pull requests and issue reviews
4. Coding, Commenting, and Committing
5. Code of Conduct

1. Welcome

Thank you very much for considering contributing to this project. Humanitarian OpenStreetMap Team (HOT) is a volunteer driven non-profit and we really rely on the community for our success. We welcome and encourage contributors of all skill levels to be a part of our development community and we are committed to making sure your participation in our community is enjoyable and rewarding. If you have never contributed to an open source project before, we are the perfect place to start and will make sure you are supported every step of the way. If you have any questions, please ask!

2. How can I contribute?

There are many ways to contribute to a project, below are some examples:

1. Report bugs, offer ideas, and/or request features by creating “Issues” in the project repository.
2. Fork the code and play with it, whether you later choose to make a pull request or not.
3. Create pull requests for changes that you think are needed. From typos and wording changes, to significant new features or major design flaws, you will find lots of opportunities to contribute improvements. Read more about coding and committing below.
4. Review or submit language translations in the Transifex TM3 project. These are later synchronized with the GitHub repository by code and project leads.

Issue or bug reports should include:

When creating an issue through the GitHub issue tracker, please include the following where applicable:

• A summary of the problem
• Any additional information you think would help us, like browser and operating system
• Any steps we might be able to take to reproduce the issue
• Any links or URLs where we can see the issue

Design and feature request issues should include:

• What is the goal of the suggestion
• The user need being addressed

Development issues should include:

• Specific code that needs improvement or dependencies to be investigated
• Rational for recommendations
• Use checklists (via - [ ]) to keep track of sub-items wherever possible

Issue Classification

During issue reviews, we try to mark the difficulty, priority, and category for each issue. If you are just getting started with the project, we encourage you to find one that is marked Easy Difficulty to investigate a manageable feature while gaining familiarity with part of the code base. If you are new to contributing but have experience in some aspect of app design, look for categories that correspond to your skills, such as UI or SysAdmin.

3. How we structure pull requests and issue reviews

Code and Project Leads

Project and code leads are experienced HOT volunteer and staff developers and the main points of contact for the project. They are also the final reviewers of issues and pull requests. Code leads will review pull requests and provide feedback. The purpose of this role is to help contributors, provide consistency and ensure code quality.

• Current code leads: Ethan Nelson (ethan-nelson)
• Current project lead: Nate Smith (smit1678)

Issues and roadmap development is overseen and discussed by the Tasking Manager Working Group. See Working Group wiki page for details.

Project Contributors

Project contributors are community members that want to be identified as project maintainers. They are there to help review issues, steer new contributors to the right issues, or write code that addresses an issue.

4. Coding, commenting, and committing

Coding style

When writing code it is generally a good idea to try and match your formatting to that of any existing code in the same file, or to other similar files if you are writing new code. Consistency of layout is far more important that the layout itself as it makes reading code much easier.

One golden rule of formatting -- please don't use tabs in your code as they will cause the file to be formatted differently for different people depending on how they have their editor configured.

Comments

Sometimes it's not apparent from the code itself what it does, or, more importantly, why it does that. Good comments help your fellow developers to read the code and satisfy themselves that it is doing the right thing.

When developing, you should:

• Comment your code - do not go overboard, but explain the bits which might be difficult to understand what the code does, why it does it and why it should be the way it is or where it might be improved in the future.
• Check existing comments to ensure that they are not misleading.

Committing

When you submit pull requests, the project maintainer has to read them and understand them. This is difficult enough at the best of times, and misunderstanding pull requests can lead to them being more difficult to merge. To help with this, when making pull requests you should:

• Split up large changes into smaller units of functionality.
• Keep your commit messages relevant to the changes in each individual unit.

When writing commit messages please try and stick to the same style as other commits, namely:

• A one line summary, starting with a capital letter.
• A blank line.
• Full description, as proper sentences.

For simple commits the one line summary is often enough and the body of the commit message can be left out.

If you have forked this project on GitHub then the best way to submit your patches is to push your changes back to your GitHub repository and then send a "pull request" via GitHub to the main repository.

5. Code of Conduct

All of HOT's projects fall under the general HOT Community Code of Conduct, which is in part based on the well known Contributor Covenant Code of Conduct.

The short version is:

• Use welcoming and inclusive language
• Be respectful of differing viewpoints and experiences
• Gracefully accept constructive criticism
• Focus on what is best for the community and the project
• Show empathy toward other community members