Hacktoberfest Help!

Katherine_Scott · 2020-10-02T17:43:58.847Z

Hi Everyone,

It is HacktoberFest again which is a great chance to get more people involved with open source, ROS, and Gazebo. The ROS community is generally very welcoming to new contributors and Hacktoberfest is a great chance to bring new developers into the fold. I wanted to take a minute to make some suggestions about what constitutes a “good” pull request and point out where and how we think Hacktoberfest participants can make meaningful and positive contributions to ROS.

In general, a good pull request makes a meaningful improvement to a project. Some maintainers of large projects outside of ROS have raised concerns about the quality and quantity of pull requests coming from Hacktoberfest. While we like to think that all PRs are good PRs, trivial and subjective PRs aren’t particularly good for either the reviewer or the submitter, and do very little to further a project or the education on new contributors. In fact, trivial pull requests may actually do harm as they take valuable time away from busy maintainers, prevent the submitter from making more meaningful contributions. To help make sure everyone’s Hacktoberfest experience a good one I’ve put together a short guide to get Hacktober students plugged into ROS and make the experience a positive one for all.

Listed below are a few examples of small but meaningful contributions that help maintainers and are a good place to start for Hacktoberfest:

Most projects triage issues and features, and may even have a “good first issue” tag. These issues are a great place to start as the project has explicitly listed them as a need.
Unit Test Improvements
- Adding unit tests that improve overall unit test coverage.
- Compacting repeated code into test fixtures.
Documentation improvements that:
- Provide concrete and non-trivial examples of how to use an API. Some repositories have an “examples” directory where these artifacts live.
- Cross reference documentation with supporting materials or original sources.
- Improve installation instructions for supported but not well documented operating systems.
- API how-tos that document common use cases succinctly.
Meaningful software improvements:
- Refactoring large code blocks (~>100 lines) while maintaining the API and backwards compatibility.
- Specific and meaningful updates to warning and error messages.
- Addressing lingering warning messages.
- Addressing documented and ticketed bugs.
- Fixing issues introduced by new versions of upstream packages.
- Upgrading ROS packages between ROS releases or ROS versions. Note that this is something usually done by a more experienced developer.
Miscellaneous
- Adding CI features that move the package up the REP-2004 guidelines.

Making a good pull request isn’t just about adding meaningful code; it should also be about lessening the burden on the maintainer, especially during Hacktoberfest. The most effective way to work well with project maintainers is to follow the rules and norms for a given project. The best way to do this is to:

KNOW your project. If you are just starting out it might be best to find a place that suits your skill level. A small, friendly, python utility library may be a better starting point for a new developer than the Linux kernel. Similarly in ROS it might be better to start with a smaller ROS package (like a gazebo plugin, or a hardware driver) than to dive right in to core components like rcl cpp.
READ the contributors file and understand what is necessary for a PR to be merged.
- The ROS 2 contributors guide can be found here.
- The Ignition contributors guide can be found here.
UNDERSTAND the project norms. For code contributions many projects will expect to see that your pull request has documentation, unit and integration tests, passes linting and static analysis, meets the specified coding standards, and has a developer certificate of origin. Look at previous pull requests to understand the process the maintainers have used in the past and follow it.
FAMILIARIZE yourself with the project before you code. Before you begin you should be able to build the project and run its unit tests. Make sure your IDE is configured to handle any formatting or linting requirements of the project.
Finally, make sure that you have met all of the project requirements before you issue your PR. Did your code compile without warnings? Did you run the unit tests successfully? Did you build the documentation? If the maintainer asks for changes please repeat this process before re-issuing your PR.

If you need help we have our own question and answer site ROS Answers. This is a great place to ask your question and search for answers.

To help make sure everyone has a good experience this year (both hackers and maintainers) we’ve put together a list of projects that are happy to have Hacktoberfest students contribute. Right now that list includes the full set of Ignition libraries, the NavStack, and the ROS 2 Docs.

If you maintain a ROS package and would like help with, and you are willing to mentor students, please let us know in the comments below. This is a great opportunity to get an extra set of hands to help upgrade your ROS repository to the latest version, or take care of longstanding issues.

Katherine_Scott · 2020-10-05T18:27:43.288Z

Hacktoberfest has moved to an opt-in model. We have opted in Ignition and are trying to figure out which ROS packages we want to opt in. Stay tuned.