First Timers Only Issues

[jennybc]

A companion issue to #45 GitHub Concierge/Ambassador Program. They are related but distinct. Again, this could be just a topic for group discussion or an actual project, possibly paired with #45.

For the general idea, which is not new, see:

http://www.firsttimersonly.com

Friendly Open Source projects should reserve specific issues for newbies.

We should open the R "storefront" for this. Maybe just sign on and reuse their framework (is there one?), but fill in particulars for R. Such as @hadley's suggestion that improving docs is a fruitful place to start. Which requires that we provide a nice guide for getting traction with roxygen comments.

More lists or resources to checkout, so we don't reinvent any wheels:

https://github.com/MunGell/awesome-for-beginners

I note the complete absence of any R projects here 😔. Maybe we can change that.

[jennybc]

Moving some comments from #45 over here:

@batpigandme: I also wonder if there might be a good way for package/repo authors to point out less technical areas where they might want help and/or an extra set of eyes.

@hadley: longer comment about pointing newcomers specifically at documentation improvements, don't make huge PR w/o consultation, fold bookdown editing into the roxygen primer

@maelle pointed out @LucyMcGowan's shiny app contributr for finding issues that were identified as beginner-friendly (in rOpenSci repos) such as this one

[hadley]

I really like the idea of some lightweight conventions around labels.

[maelle]

Github valetting at its best (moving comments to the right issue) :ok_hand:

[jennybc]

I think making README.Rmd that features some actual usage is another general category of early contribution. Especially for packages whose sole documentation is the manual. Would require developer "sign off" because it obligates them to something new, in a small way.

[LucyMcGowan]

for contributr we decided on "Beginner" as an easy label to add & @sckott and @maelle put it on some rOpenSci repos to test. @maelle and I brainstormed some rules for writing beginner issues, for maintainers, and for first time contributors - would love input! (note: right now the shiny app is down because my account was suspended for exceeding usage hours but I'm hoping to move it to an rOpenSci account soon)

[sfirke]

I love this idea. It's a great way to build the pipeline of people contributing to open source software. I remember my first PR well, it was empowering and made me feel so proud even though it was probably <100 characters.

[hadley]

@LucyMcGowan send me an email about the shiny app and I might be able to do something about it

[maelle]

@sfirke http://firstpr.me/#sfirke :wink:

[sckott]

(@LucyMcGowan just sent you creds)

[sfirke]

@maelle it is a great example of what we're talking about. @hadley could have written the test and NEWS.md bullet faster than patiently correcting me when I didn't write the test correctly, etc. but it was a better experience for me getting to do it. That was my first experience with a pull request, first time looking at a test, etc. I did all of the Git stuff in the GitHub web UI (including some file editing) because I hardly knew any Git. That PR took me several hours - but it was a first step into something wonderful 🌞

[batpigandme]

@LucyMcGowan Looks really neat. I think this is the type of thing that really benefits from having a bunch of contributors (beginners and pros, alike) as the barriers to participation will likely vary by background (and a variety of other factors).

[hadley]

My first PR is also a pretty good example of how you can contribute http://firstpr.me/#hadley

[jennybc]

In true form, mine is renaming files and filing them neatly in subdirectories 🤓 http://firstpr.me/#jennybc

[batpigandme]

This is a minor point, but one of the things that can make it hard for beginners to find some of the existing resources is not knowing whether it's still "relevant" based on age/how old it is-- i.e. is what's being said here still current? Also,sometimes it's not clear whether a problem is a user problem (result of env't or stack in place) or an actual issue.

Just trying to think of some of those fundamental barriers (many of which are addressed in the reprex docs, and talks).

[karthik]

This is a minor point, but one of the things that can make it hard for beginners to find some of the existing resources is not knowing whether it's still "relevant" based on age/how old it is-- i.e. is what's being said here still current? Also,sometimes it's not clear whether a problem is a user problem (result of env't or stack in place) or an actual issue.

💯. I notice this often. People point to R packaging guides that are super old (and many tips and routines mentioned there are just outdated). Even when I get busy and step away from full development for a bit, I see a ton of new stuff. I just started collating some material around R development this morning, but perhaps it could become an unconf project if it could become a community maintained resource.

[batpigandme]

@karthik It's one of the reasons I really like when authors use sessionInfo(), but something could be both old and right. Perhaps something to the effect of a periodic updating with "current through"? Though it'd be hard to make that any sort of "real" convention, including on the viewer's end.

[jennybc]

This reminds me of bridge bidding convention cards. If you've never played, this is a card you show opponents (!) to explain the basic system you and your partner use.

Packages that welcome contributions need this!

I can tell by looking a repo that someone uses snake_case, testthat, roxygen2 w/ Markdown syntax, README.Rmd, etc but a newcomer probably needs to be told which system the developer uses.

Basically "this is how we do things around here".

I suppose this is what CONTRIBUTING.md is for? But the resources for first-timer issues could also explain to people how to figure this stuff out for themselves. It's a pretty finite set of things to look for.

[batpigandme]

@jennybc totally agree, esp. re. a sort of flowchart of forensic-dating of packages (the easiest being that it's visibly noted --> set of things to look for etc.)

[batpigandme]

I also wonder if there could be a web-annotation type solution when it comes to tutorials and documentation (possibly even allowing collaborative annotation). Example, just happened to be looking at @jennybc & Shaun Jackman's Automating Data-Analysis Pipelines slide deck: there's a lot in there that's undoubtedly "current" bc it's conceptual, or about workflow, etc.; however, I see the date (in 2014), and, as someone who hasn't dealt with make files, I'm not sure which pieces hold true. (Not a critique of this deck at all, just my most recent example today).

[njtierney]

On the note of the CONTRIBUTING.md doc, @jennybc

I've noticed in the tidyverse packages that there is now an automated issues template, which is really cool, because it sets the expectations. Such templates are also in the ropensci onboarding

Perhaps one approach could be that those packages/repos who sign up for the firsttimersonly, are also required to have standard templates for their issues and pull requests? This could then include helpful beginner information?

Also, does anyone know how you actually include these issue/pull request templates? They are really cool! I wonder if they could be automated, something like a add_issue_template function, perhaps?

[jennybc]

Here's how you create issue templates from a GitHub point of view:

https://help.github.com/articles/creating-an-issue-template-for-your-repository/

Anecdotally, I think it's safe to say that a lot of people just ignore the template (@hadley might weigh in on this). But that doesn't mean we shouldn't try to use them for good.

[njtierney]

Thanks! :)

[hadley]

FWIW it's worth I'd say the issue template is a failure: effectively no one reads it and then it makes me more annoyed that people just delete it without reading.

[njtierney]

Ah dang, that's a shame! Esp. because they would have to actively delete it.

Perhaps we can hope that to instill best practices in those who are part of the firsttimers contributions.

[MilesMcBain]

For those who maintain popular packages:

When an issue comes in the form a bug report, would a useful task for new helpers be find/confirm environment and configuration that reproduces the error?

Recently I have started turning to docker containers to try to isolate errors in a minimally configured environment, and it feels like I'm getting to the root of things faster. If someone turned up and provided a container and code that reproduced a bug I would be pretty stoked.

It's a shame this can't done easily for Windows and Mac specific stuff, but it is at least kind of possible on Windows using public VMs.

[hadley]

For me, that's useful about 5% of the time, and the rest of the time just adds noise to the bug report. Most issues are usually easily reproducible with the CRAN version - I just need a solid minimal reprex to start from.

[MilesMcBain]

Yeah that makes sense. Reprex quality > isolating environment. Thanks.

[MilesMcBain]

Helping elicit the reprex and then adding a test case that captures it. Maybe that's a better newbie friendly task?

[hadley]

I don't think a test case is necessary, it's better to focus on getting a minimal reprex first.

[jimhester]

It would be nice to have some conventions around intermediate level issues motivated people could take on as well. There have been times where I wanted to contribute to a project, but didn't know what features were in the pipeline I could try to implement. I would think these would be geared more to new features, bug fixing is largely a thankless task, unless it affects your workflow.

[maelle]

When I wrote a blog post about ropenaq for rOpenSci's blog @stefaniebutland asked me to add both beginner and intermediate level issues to the repo. I have one intermediate issue

[hadley]

Another reason that I don't love encouraging people to write test cases or use containers is that a lot of issues get closed because they're out of scope. A reprex is always helpful, but I don't want people to spend a bunch of time on something that I'm just going to close.

[hadley]

Improving a print method is also a nice way to contribute: https://github.com/hadley/emo/pull/2

[stephlocke]

I'd be interested in improving the way I encourage, facilitate, and mentor new contributors. For my pRojects package I've got up-for-grabs and first-timers-only but coding conventions etc seem eminently sensible to give people too.

I often add my projects to up-for-grabs.net

[stephlocke]

I like what @rich-iannone is doing with his issue backlog for DiagrammeR https://github.com/rich-iannone/DiagrammeR/issues

[batpigandme]

@stephlocke Yes! It also automatically bounces you to certain issues from the documentation if it's a known problem area.

[hadley]

Great guide at http://buff.ly/2pRURMI

[hturner]

@LucyMcGowan http://www.charlotteis.co.uk/open-open-source/ has some tips for writing issues particularly for beginners, might have a few points to add to your guides.

up-for-grabs.net allows you to add your project as a whole, then will show the number (even if zero) of issues currently with that tag. It seems only one tag is allowed though, so need to decide whether you want to advertise any issue up for grabs, or just beginner issues. No projects tagged with R at present.

contributr has several advantages: being focused on R, showing the actual issue, providing guides to get started...but it would be nice if adding a repo there would also mean getting added to up-for-grabs - this reaches out to people already familiar with up-for-grabs from other languages.

"beginner" is a good label as it is easy to search on GitHub, e.g. label:beginner is:open; label:"Difficulty — Intermediate" is:open is a bit of pain in that sense.