Skip to content

Latest commit

 

History

History
128 lines (91 loc) · 5.52 KB

maintenance-guidelines.md

File metadata and controls

128 lines (91 loc) · 5.52 KB

Open source maintenance guidelines

This document details Embark's guidelines for open source project maintenance. All our open source projects have explicit maintainers who are responsible for managing the project and adhereing to these guidelines.

Share responsibility

Maintaining an open source project can at times be tiring or time-consuming. If possible, find another Embark employee to be a co-maintainer of the project, in order to share the workload and support each other.

Write detailed issues

Ensure all issues have sufficient context so that people reading them can understand what they mean, even if they are less familiar with the project. If the issue is intended to be worked on by community members, add additional information to help them get started with the implementation. This is especially important for issues marked “good first contribution”.

Label issues

If there is an issue for which you would welcome a contribution from someone outside of Embark, label the issue as “help wanted”.

If you wish to encourage new contributions from outside of Embark, and you have the time to review and guide contributions from people less familiar with the code base, label less challenging issues as “good first contribution”.

Assign issues

If someone is working on an issue, assign it to them so that other people know not to attempt to work on it.

Respond in a timely manner

Respond to issues and pull requests from people outside of Embark as quickly as possible, aiming to leave the submitter waiting no more than two working days.

If you are unable to resolve the issue or review the pull request within that period of time, leave a reply letting the submitter know that you have received the issue or pull request, and that you will get to it at a later date. Not knowing the status of your work or problem can be frustrating!

Be courteous

When interacting with people as the project maintainer be sure to be clearly polite and respectful, and thank people for their contributions. This helps build goodwill towards the project, encouraging future contributions and improving our reputation.

Assume positive intent

Contributing to open source can be stressful or intimidating, English may not be their native language, or they may have had a particularly bad day. Any of these reasons or more can result in people coming across as abrasive or rude. Where possible, assume that any rudeness is an unintentional accident and attempt to maintain a polite and friendly atmosphere.

Offer clear guidance

Offer advice and context on how to implement a feature, and give clear and actionable feedback when reviewing pull requests.

With simpler contributions, it may be more time-consuming for you to offer this guidance than it would be for you to just implement the feature yourself. Nevertheless, it is still worthwhile doing this as it helps the contributor to learn, building goodwill towards Embark and the project, and making it more likely they will make more contributions in future.

Say no when required

There will be times when community members suggest or contribute to changes that are not suitable for inclusion in the project, either due to a low quality bar or because the changes are out of scope for the project.

If it is possible for the contributor to improve the quality of their contribution so that it can be merged, explain the issues to them and offer guidance on how to improve it so they can submit further changes later.

If the issue or contribution is out of scope for the project, politely explain this to the contributor along with any reasoning, and then close the issue, thanking them for their contribution.

Close stale pull requests

If a pull request is in an unfinished and un-mergeable state, and the contributor has not made any updates or indicated that they are currently working on it for over 2 weeks, close the pull request. Closing stale pull requests makes it clear the project is maintained, and makes it easier to tell the current state of work on the project.

When closing leave a message thanking them for their contribution and inviting them to reopen the pull request when they have further changes.

Perform hand-overs

If you are unable to maintain the project for a period of time, e.g. if you are going on holiday, find another person at Embark to temporarily take over your responsibilities. Add to this person as a code owner to the repository to ensure they get appropriate notifications to new issues and pull requests.

If you are leaving Embark or no longer have the desire or capacity to maintain the project, find another person to adopt the role of maintainer.

If you are unable to find a suitable person, contact the open-source team for help.

Get help from the open-source team

If you find yourself in a situation where you’re not sure what to do, reach out to the open-source team for support. They can be reached via the #opensource channel in our internal Slack.

Adhere to the code of conduct

All open source Embark projects have a code of conduct which details the expected standards of behaviour to which all community members must adhere. Read the code of conduct and ensure that both yourself and your contributors follow it. If you have a problem with a community member violating the code of conduct reach out to the ecosystem team for help.