Helping "new" users contribute


#1

I’ve been happily using Julia for 3-4 years and would like to try contributing to other packages than my own however

  1. I often don’t really know how to (I do know how to make a PR but not up to what extent it’s ok to suggest a PR for an example or a comment for a use-case etc), many repos seem to lack a “CONTRIBUTING” file & where some maintainers may be happy with newbie (clumsy) modifications, I could understand others not being too happy about it, so having a file to guide people could be useful. Having a list of things that need be looked at would also be useful.
  2. I often don’t know where to ask usage questions / comments. Issues seem inappropriate because they usually relate to the code itself, email would be overkill for maintainers, discourse can be good but it feels far from the repo, slack is too short-lived and Stack Overflow can be a bit scary for “simple” questions and feels inappropriate for comments / discussion.

Maybe it’d be good to suggest general Julia guidelines for package devs & users to collaborate better? for example

  1. recommend there be a friendly “CONTRIBUTING.md” doc on all repos, maybe add a “walk-through-first-PR” somewhere in the julia universe (maybe it exists and I haven’t seen it). There’s scattered resources on how to create and register a package (e.g. by Chris R :ok_hand:) but I couldn’t find a kind of “suggested checklist” that would for example include adding a contrib file or good practices. Maybe that PkgDev.jl could generate a template contrib file like it does with the license.
  2. not sure about the second one (and it may have already been discussed elsewhere): maybe a way around is to suggest that Julia repos do indeed use “issues” for usage questions/comments (possibly with a usage label) allowing not only the maintainer but also other users to reply which would then eventually form a kind of repo FAQ and lead to PR with usage examples.

#2

My experience is that PRs are welcome, especially if they have tests. It’s tempting to ask “hey would this be well received”, but my experience is that mostly those go unanswered, or at least it never feel definitive. It’s easy to say no, I haven’t seen anybody get offended by a PR. I feel similar to you in that I have moderate experience with Julia and zero experience with open source development pre-Julia. But I’ve made a few PRs, and every one has received comments (only one too more than a week or two to get a response), and most were merged. julia/CONTRIBUTING.md has lots of good info, though I remember seeing something more specific to packages.

For 2 I’d say everybody is probably better off if you ask the question somewhere rather than nowhere, even if its not the best place. I would go with Stack Overflow, and maybe file an issue if your question goes unanswered for a while and you suspect there just aren’t many users of the package.


#3

What works really well for my project is for prospective contributors to open an issue to propose their PR, and then we can have a bit of a discussion to flesh things out, and then the contributor submits the PR and all the questions about “will this be well-received?” have already been addressed and now it’s just a matter of style conformance. Give that a try and see how it goes. I’m pretty confident in saying most projects would LOVE more contributors.


#4
  1. Quick question on Gitter or Slack, to see what the package devs / users think of the proposed change
  2. Possibly follow up with a topic here on Discourse, if it’s still in doubt
  3. Then post issue or go directly to a PR (depending on responses from 1) and 2).

I’d love to have contributions to the string related packages I (and others!) have been working on in juliastring.org, testing, ideas, documenation, code, it’s all good!


#5

I am totally fine with people asking for support in issues. Maybe packages that encourage this should say so in their README.

I usually contribute to packages where I want something fixed. In cases where my approach had been suboptimal, I always got a lot of helpful advice. Larger projects may benefit from guidelines, but for small packages you just get a feel for the style from the source.


#6

I created a Gitter chat room for juliastring.org, and then put a badge pointing to it at the top of the README.md in pretty much every package there.


#7

Thanks, very useful feedback. I haven’t used gitter so maybe I should try, I find Slack hard to follow.

How do you advertise what you guys need help with on your packages if not on a gitter?


#8

Check the tags in repo issues - frequently there is some sort of indicator (such as “help wanted” “good first issue”).