first-timer-only issues

[tylerjw]

Background

This idea was inspired by a talk I listened to from GSoC. Here is a link to a blogpost that discusses the idea. Here is a link to a github issue from the author of the talk.

The basic idea of this is to lower the barrier of entry to contributing for people who are new to moveit and/or open-source. This does not generally mean that they are necessarily beginners at creating high-quality code, just that they might not have contributed because they saw the task as confusing or hard to know how to get started.

I created the first issue along these lines here: #2383

This issue is for discussing the idea of first-timer-only issues and developing the template and user experience for first-time contributors. The downside to creating issues like this that we could easily just solve ourselves is that they will take longer to guide new people to do than to just solve them ourselves. The upside is that they will bring new contributors into the community and hopefully once they have gotten the experience of landing their first change they'll be inspired to take on larger issues.

Tasks to give this the best chance of success

• Update moveit.ros.org page on contributing to include a list of first-timer-only tagged issues.
• Create a first-timer-only template for issues. [meta] first-timers-only issue template #2385
• Write a guide on how to create a first-timer-only issue and encourage people who land their first PR to create one for someone else. (Consider using github bot for this)
• Write more first-timer-only issues.

first-timer-only Issue ideas

@felixvd

1. make the environment variables like CATKIN_WS work in the master-source docker container so clang-tidy commands can be copy-pasted directly from the instructions
2. add convenience scripts like bash aliases to run clang-format/clang-tidy in the docker container
3. add simple instructions to use docker, including a way to link a workspace that’s visible on the host hard drive (many first-timers are not fluent in linux+CLI+docker)

References

https://code.publiclab.org/#r=all
https://kentcdodds.com/blog/first-timers-only
https://www.firsttimersonly.com/
https://github.com/MunGell/awesome-for-beginners
https://github.com/firstcontributions/firstcontributions.github.io

[tylerjw]

@felixvd I created a couple of issues using the new template. One was based on issues you listed as problems for first-time users: #2409

Would you mind contributing similar issues using the templates for the two other issues you brought up:

1. add convenience scripts like bash aliases to run clang-format/clang-tidy in the docker container
2. add simple instructions to use docker, including a way to link a workspace that’s visible on the host hard drive (many first-timers are not fluent in linux+CLI+docker)

The second one I'm really curious about. I don't currently use docker in my normal workflow with moveit (I use lxd though because I find it useful for my uses although it is not really begineer friendly) and maybe I should be.

[davetcoleman]

This is an awesome progam @tylerjw !!

I'm working on the new website pages to make it easier for new users. I'd appreciate your feedback, then @auman66 will be leading the design and development of the pages.

• Get Involved page
• Contributing page
• Roadmap

[felixvd]

(Pasting my post from the other issue)

Now that we have tried this for a few months, I think we should take stock and discuss what the desired effect and the scope of these first timer issues should be. I am not sure that it's meaningful to provide the whole diff as in #2424 (what is the learning effect?), or that lowering the complexity that far attracts people who are likely to contribute in the future (no offense, I am not targeting anyone who submitted before). And if it doesn't feel time-cost-effective to the people who can write these issues, the idea will end up abandoned.

Personally I imagine the ideal first-timer issue (or "good first issue") to involve less than 20-40 lines of code, a limited understanding of the code base (grokkable within 1-2 days of reading as a beginner/intermediate coder) and a readiness on the part of the original poster to fix up the submitted code themselves (to provide a learning experience and to avoid excessive back-and-forth). Are we imagining the same thing? Is the current template helpful for this? It seems quite long to me, inviting people with almost no experience. That's not a bad thing, but I think there is a middle ground to be struck between that and the open-ended bug reports that need a lot of time and knowledge to fix.

People who have claimed (or wanted to claim) a first-timer issue are also welcome to join this discussion.

PS: We probably all agree that we should motivate newcomers to tackle issues with limited scope (Github says that they now point them to this page, so using the good first issue label would be a start (see #2516) regardless).

[simonschmeisser]

I agree with what Felix very politely expressed and think that we should stop adding more first time issues that can be "solved" by two clicks and copy-paste in the github web interface. This just adds work on our side.

What could be a lot more rewarding is to better support intrinsically motivated newcomers (ie graduate students with a project of their own) in getting the hurdles they encounter out of their way. This could be "implemented" by just including an invitation to create a PR together in answers to issues here or on answers.ros.org Of course we would then also need to merge those PRs in a timely fashion (review seems to work already).

[davetcoleman]

We've just launched the new contributing page, with info on "Good First Issue". We've removed the first-timer-only approach, per @felixvd

Seems this issue can be closed.