9 ms·

First Timers Only

510 points by MindTwister 11y ago

thanatropism 11y ago
... and this is a prime example of the "developer ergonomics" v. "end-user needs" trade-off that was being discussed a few days ago re: web frameworks. I mean, it's very well possible that the long-term investment in expanding the "base" of willing coders is worth the short-term loss in productivity. But even long-term investments in human capital need better planning than just "hey, I bet a high-schooler could deal with this simple accounting spreadsheet; that would train him even if it takes him a day to fix what I can fix in ten minutes". It's fine investing in high-schoolers, sure, but that's not the point.
- geon 11y ago
  What is the point?
  - thanatropism 11y ago
    The point is that the tradeoff between making things at optimal productivity and using thing-making as an educational opportunity exists. The OP's initiative may come at an excellent cost-benefit price, but it's questionable whether they even considered the tradeoff. And if they have, it's still important to discuss it if it comes to an internet forum.
    - geon 11y ago
      He already had the implementation ready, but choose to not push it to github in order to encourrage participation. Clearly, productivity was not a priority.
      - NiloCK 11y ago
        Today's productivity wasn't a priority for the author, but tomorrow's productivity is the goal. edit: A proverb: If you want to go fast, go alone. If you want to go far, go together.
    - deleted 11y ago
      [deleted]
    - camone 11y ago
      It was pointed out in the article and he did consider it. " Now, could I have finished it quicker and moved on my way if I’d just done it myself? Of course. But that’s not what it’s all about as an open source contributor. It’s fun delivering good software that helps other people, but also realize that there are tons of people out there who just don’t know where to get started. Some of you may be asking yourself, “what if I (and other lib users) don’t want to wait days for the feature?” From my experience, people are eager to try it out. At least one PR (sometimes several) is submitted, iterated on, and merged within a matter of a few hours. "
TerryADavis 11y ago
I have a talking SETI. $100,000,000
pella 11y ago
similar : Mozilla "Mentor Bugs If you are looking for a bug with guidance, we maintain a set of bugs that are marked with an assigned mentor (see "Whiteboard" field). The mentor will help you get the necessary information to understand the issue, point out relevant parts of the code to look at, etc. You can browse these bugs on Bugs Ahoy!, but here's a list of unassigned mentor bugs to get you started:" https://wiki.mozilla.org/Mobile/Get_Involved#Mentor_Bugs https://wiki.mozilla.org/Mobile/Get_Involved#Mentor_Bugs Other examples: #easyfix: https://github.com/facebook/flow/labels/easyfix https://github.com/facebook/flow/labels/easyfix #beginner: https://github.com/eslint/eslint/labels/beginner https://github.com/eslint/eslint/labels/beginner #exp:beginner https://github.com/docker/docker/issues?q=is%3Aopen+is%3Aissue+label%3Aexp%2Fbeginner https://github.com/docker/docker/issues?q=is%3Aopen+is%3Aiss...
- masklinn 11y ago
  > Other examples: Rust has E-easy and E-mentor https://github.com/rust-lang/rust/labels/E-easy https://github.com/rust-lang/rust/labels/E-easy https://github.com/rust-lang/rust/labels/E-mentor https://github.com/rust-lang/rust/labels/E-mentor
- larsberg 11y ago
  We also try to have good starter bugs on Servo (and its myriad dependencies): http://servo.github.io/servo-starters/ http://servo.github.io/servo-starters/ One of the biggest challenges we have is keeping some around and available! The good ones almost always have an opened PR within 24 hours: https://twitter.com/ServoDev/status/665930502503723008 https://twitter.com/ServoDev/status/665930502503723008 There are a bunch of other benefits to these bugs, including: - There's a lively stream of people setting up the dev environment for the first time, both keeping our instructions up to date and making sure we handle scenarios like slow internet connections, really old versions of Ubuntu or Linux graphics drivers, etc. - Reviewing these bugs is also a good way to help grow contributors from committers into reviewers/maintainers. Most of our challenges with these kinds of bugs are related to GitHub. e.g., you can't "assign" an issue to somebody outside of the project organization, so somebody has to manually label it "Assigned" for our filters to work. Also, you don't get notifications when somebody pushes a new commit to their work branch or rebases, so there's a lot of manual watching of these PRs during the review cycle that sometimes gets dropped (though our myriad GH bots could probably fix this!). Even with the challenges, we love having this kind of bug as a way to bring in more contributors and keep development on the project accessible, and like the author, I'd highly recommend it to other projects.
jedanbik 11y ago
Mentorship in OSS makes everyone involved a little bit better at something, be it following instructions, learning practical tooling, writing clear instructions, justification of process and habits, etc.
MindTwister 11y ago
Huh? Says I posted this 2 hours ago, but I'm pretty sure I posted it yesterday
- frostmatthew 11y ago
  I believe if dang (and perhaps others) finds a submission that would probably be interesting to a lot of HNers but didn't get much/any traction when initially posted it is "resubmitted" to give it another chance.
- mkagenius 11y ago
  When you feel anything like that, you should say "dang it" ;)
jondubois 11y ago
There are a lot of ways to contribute that don't involve making pull requests. Identifying and raising issues is a good place to start for someone who is not familiar with the codebase.
- Bahamut 11y ago
  A caveat to that is that they need to be well-researched before filing issues - otherwise it actually is a negative, especially when a modicum of effort reveals when something actually is a usage issue and not a bug.
  - jacquesm 11y ago
    If only that was made easier. And then, of course it also helps if the majority of the bugs you raise are not flagged 'wontfix', which does wonders to encourage further reporting.
  - jondubois 11y ago
    I actually don't mind if users report 'issues' which turn out to be their own fault. In some cases this could indicate that a feature in your project isn't intuitive enough. Also I like having as many issues as possible - It creates a knowledge base for your project which people can search through.
- mfringel 11y ago
  In my experience, raising an issue is followed by "okay, so fix it.", which reduces to a previously noted problem.
batrat 11y ago
This titles man are worst than FB. Why not just "Click here!"?. Or could just copy and paste the title: "A suggestion to Open Source project maintainers"
ant6n 11y ago
As a bit of a nitpick, I find it slightly ironic that this article uses TDD and PR as unexplained abbreviations.
- crottypeter 11y ago
  TDD is acceptable as it is the top search result for TDD. PR on the other hand ... Acronyms and abbreviations with well defined / well known alternative meanings really bug me. Actually Acronyms and abbreviations bug me full stop.
  - ant6n 11y ago
    Well, I googled both, which kinda bugs the flow of reading the article. Abbreviations bug me too.
    - ithinkso 11y ago
      Well, what about RAM, PC and so on? They might be an extreme example but if you are in the 'field' not using abbreviations may actually bug you more. Targeting audience is not an easy task.
      - ant6n 11y ago
        Didn't have to google RAM, PC and so on.
      - yoha 11y ago
        It is often better to use “computer” and “memory”, especially when the distinction between L1/L2/L3/RAM/SSD/HDD is not the main topic.
  - rcraggs 11y ago
    The people who will benefit from this article most are people who lead OSS projects, so I don't think it's too much of a problem to use these.
- kentcdodds 11y ago
neogodless 11y ago
As a true open-source zero timer, I can't quite figure out what PR means. My gut was "pull request" but it sounds like you're "committing a fix" at this point, so I suppose "push request" might be the answer, but it's an ambiguous pair of letters.
- hartator 11y ago
  It's pull request, that's git terminoly to merge external code to an existing project.
  - diggan 11y ago
    I don't want to nitpick but for a Git beginner (not necessarily you but others reading here), it's important to know that "pull request" is really a Github concept, not a Git one.
    - realityking 11y ago
      Pull request is very much git terminology. Here's the documentation for 'git request-pull': https://git-scm.com/docs/git-request-pull https://git-scm.com/docs/git-request-pull
      - ultrafez 11y ago
        If you're being picky, then I can be picky too: the concept of a "pull request" isn't defined in that manpage, only the command "request-pull" is. A "pull request" is an entity in itself. The command may exist within git, but it's not a part of most people's git workflows. "Pull Request" is a term that's far more commonly attributed-to and associated with tools like GitHub, Gitlab, Bitbucket etc. Did you know that git has the ability to send patches via email, built in [1]? Git has a lot of functions that the majority of people don't use. [1] https://git-scm.com/docs/git-send-email https://git-scm.com/docs/git-send-email
        realityking 11y ago
yandrypozo 11y ago
This world needs more people like you. Thank you !!
J_Darnley 11y ago
As far as I can tell this information is specific to Github and development on Github. Why is CONTRIBUTING.md important? Its just another file for someone to read alongside COPYING, INSTALL, README, TODO, and perhaps what's in the doc/ directory. And why markdown? Organising and comments are good but people have been trying to get devs to do that for decades and we're still mentioning it. "Add an up-for-grabs label" to what? Where? How will people see this? Adding a githook might be useful on a remote repository but I don't want to run a full test suite every time I commit, ammend a commit, rebase, or otherwise trigger it. What's NPM? Why would anyone use it over a makefile? I would extend my first comment and say this is for javascript projects which use Github and only Github.
- deleted 11y ago
  [deleted]
- tnorthcutt 11y ago
  Replace all the language/framework/code-hosting specific terminology with whatever suits you. The attitude and willingness to help newcomers is the point. The author just used his project and experiences as a way to illustrate that point.
- wtracy 11y ago
  CONTRIBUTING.md is important because it provides an easy entry point for new developers. Out of COPYING, INSTALL, README, and TODO, where do you go to answer that question? Except for TODO, all those files are targeted at end users, not contributors. The choice of Markdown is of course entirely arbitrary. The up-for-grabs label goes in your bug tracker. Then anyone can see it by browsing open bugs. NPM is the package management tool used by Node, not a build tool. I think that Node having its own package manager is ridiculous, but since Node development already requires it, there's no reason for this project to not make full use of it. Outside of using NPM, I don't see anything web-specific, and outside of Githook I don't see anything git-specific. Even Sourceforge gives you a bug tracker!
javajosh 11y ago
Great idea. I would add: if someone tries to do contribute something, but maybe they have a git issue, don't step in and push it yourself. This happened to me on one project, and it bothered me so much that I stopped contributing entirely (which was the right move, it turned out).
amirmc 11y ago
We've a curated set of Pioneer Projects for MirageOS [1], where more established contributors have agreed to act as mentors for newcomers. It's worked really well for us! One of the unexpected benefits was that we could quickly take part in things like Outreachy and GSoC, as we already had a curated list. Reviewing this list every few months has become part of the normal process now. In addition, asking people to act as mentors also gives them a different perspective on the existing code base, especially where things are particularly thorny. [1] https://github.com/mirage/mirage-www/wiki/Pioneer-Projects https://github.com/mirage/mirage-www/wiki/Pioneer-Projects
munchor 11y ago
At elementary OS we have "elementary Drive By Contributors" :) https://launchpad.net/~elementary-driveby https://launchpad.net/~elementary-driveby
- thewhitetulip 11y ago
  I have found the team to be obstinately stubborn about changing minds
thewhitetulip 11y ago
This is a really nice initiative, when I was starting with open source development I had no idea how to do what we needed to do and almost no project i talked to had any initiative like this where they keep some part of their project open for first timers like me, i had to struggle a lot to get started, it'd be great if more and more influential projects started to use this and if they were a little more open to feedback, of late I have noticed those who manage the project just don't listen to feedback what so ever.
BinaryIdiot 11y ago
Great read. My favorite part is this bullet point: > Use npm scripts so people don’t have to understand or globally install any build tools I do this on every project I work on. In fact, where possible, I completely skip globals entirely (for instance in my msngr.js library it uses Grunt but it executes grunt locally without it being installed globally on the machine). I think it's really important that anyone can go up to a library, pull it down, and start it with little to no further effort. The less friction you can provide a developer the better.
- chowes 11y ago
  100% agree.. and just as important as ease of starting: ease of finishing. make all of your tests / linters / etc. runnable via a simple npm run. there's overhead in setting this up, but i can remember several times where i have pulled the code down, made my changes, and gave up when trying to figure out how the maintainer wants my code formatted / tested.
- peterjmag 11y ago
  Agreed! This saved us all kinds of headaches in a large project at my old company (not open source in this case, but still helpful). I left a similar response on Medium before I noticed your comment: https://medium.com/@peterjmag/great-tip-d6fcdec36e13 https://medium.com/@peterjmag/great-tip-d6fcdec36e13
eitland 11y ago
Jenkins has been filling my twitter feed with information for new contributors lately under the hashtag #hacksgiving I think. Edit: Changed "spamming" to "filling" That was meant as a positive thing but I guess I shouldn't have used the word spamming.
- deleted 11y ago
  [deleted]
- eitland 11y ago
  Anyone care sharing why I keep getting downvoted for this one? By all means feel free but this one was more than a little puzzling to me : )
  - J_Darnley 11y ago
    Probably because you used "spamming". Or you spoke poorly about someone's favourite tool.
jakejake 11y ago
This is really great. I've contributed to lots of projects and it would be nice if maintainers were all this thoughtful. If not actively encouraging people to get involved, it would be nice of maintainers to simply acknowledge or appreciate someone's effort. I've contributed a lot of code and have had vastly different experiences. Sometimes people are excited and accept a PR without question. Some people just ignore PRs. Some people make you feel as though you've just spit in their face. I had one pull request that I thought was reasonable which was met with a ridicule from the maintainer at how useless my idea was (to him). I'm a seasoned programmer with my own projects and a lot of code under my belt but, even knowing how these things work, that one really soured me on his project. I can't imagine if a novice who was excited at their first PR was treated so poorly. If I could suggest anything to maintainers, it would be to simply appreciate that somebody was trying to contribute. If their code doesn't meet your goals or standards, try to still respect that they spent some time on your project.
nartz 11y ago
I think the KEY thing here is that you wrote the tests, that gave someone the 'confidence' to say whether or not they were even on the right track - this is amazing - the tests give exactly the right context for someone to dive into the code.
twic 11y ago
A related effort: https://twitter.com/yourfirstpr https://twitter.com/yourfirstpr
alexc05 11y ago
One thing that he left off his list of things to make contributing successful is seeking up a "docker" box which is ready to go for development. (Or a vagrant file) If the image is set up so it "just works" and has all tools preinstalled, you can be up and running locally in seconds. With NPM scripts, its often possible to run I to problems with node-gyp... Or any other number of cross platform incompatiblities. The docker/vagrant route is a really novel solution I've seen used effectively in other projects.
metasean 11y ago
Along the same lines, I'd encourage everyone, first timers and grey beards alike to check out http://24pullrequests.com/ http://24pullrequests.com/ (they use a 'beginner' instead of 'first-timers-only' as their novice-friendly tag). If you're in the Salt Lake area, also please consider joining us next Saturday [1] or Tuesday, Dec. 15 [2] as we give a little back to the Open Source community! [1] SLC JS Learners - monthly JavaScript Study Group - http://www.meetup.com/SLC-JS-Learners/events/224563977/ http://www.meetup.com/SLC-JS-Learners/events/224563977/ [2] SLC JS Learners - monthly meetup - http://www.meetup.com/SLC-JS-Learners/events/226862778/ http://www.meetup.com/SLC-JS-Learners/events/226862778/
peterjmag 11y ago
I love this. I've been thinking about a very similar issue for a while now, and I'm still trying to organize my thoughts into a blog post or something, but here's the basic idea: Hire more juniors. Or cross-train people from other departments[1]. Doesn't really matter who. But they should be pretty darn close to beginners. Assign a relatively small issue to them. The kind of thing that would only take about an hour for a more senior dev to look in to. Plan more than an hour for the junior. Probably a lot more. Also plan some time for one of those more senior devs. Sit them down next to each other. Point the junior to the readme. Ask the junior to ping / poke / bother the senior every time they hit a roadblock. Every single time. Ask them to be relentlessly persistent. (Not everyone's good at being relentlessly persistent. So encourage them. Create an environment where they feel like they can be relentlessly persistent.) Then leave them alone. Give it a day or two. Watch as interesting things start to happen. Watch as the junior dev learns how to be a better communicator. Watch as they learn how to make problems visible. How to get help. And as an added bonus: how to program. Watch as the senior dev goes insane at first from all the questions. Watch them start to wonder how they can avoid going through this every time somebody needs to touch their code. Watch them remove obstacles. Or at least reduce their number. Watch them automate things. Or speed up things that are already automated. Or improve processes in ways they had never even considered before sitting with the junior. Also watch them learn how to be a better communicator. Do this a few times. Watch for magical things. Code quality improves. Onboarding times plummet. Hiring friction melts away. Teamwork starts... working. Productivity skyrockets. Job satisfaction goes up. Happiness prevails. ----- [1] See also https://twitter.com/patio11/status/657902663686754304 https://twitter.com/patio11/status/657902663686754304

510 points by MindTwister 11y ago

... and this is a prime example of the "developer ergonomics" v. "end-user needs" trade-off that was being discussed a few days ago re: web frameworks. I mean, it's very well possible that the long-term investment in expanding the "base" of willing coders is worth the short-term loss in productivity. But even long-term investments in human capital need better planning than just "hey, I bet a high-schooler could deal with this simple accounting spreadsheet; that would train him even if it takes him a day to fix what I can fix in ten minutes". It's fine investing in high-schoolers, sure, but that's not the point.

geon 11y ago
What is the point?
- thanatropism 11y ago
  The point is that the tradeoff between making things at optimal productivity and using thing-making as an educational opportunity exists. The OP's initiative may come at an excellent cost-benefit price, but it's questionable whether they even considered the tradeoff. And if they have, it's still important to discuss it if it comes to an internet forum.
  - geon 11y ago
    He already had the implementation ready, but choose to not push it to github in order to encourrage participation. Clearly, productivity was not a priority.
    - NiloCK 11y ago
      Today's productivity wasn't a priority for the author, but tomorrow's productivity is the goal. edit: A proverb: If you want to go fast, go alone. If you want to go far, go together.
  - deleted 11y ago
    [deleted]
  - camone 11y ago
    It was pointed out in the article and he did consider it. " Now, could I have finished it quicker and moved on my way if I’d just done it myself? Of course. But that’s not what it’s all about as an open source contributor. It’s fun delivering good software that helps other people, but also realize that there are tons of people out there who just don’t know where to get started. Some of you may be asking yourself, “what if I (and other lib users) don’t want to wait days for the feature?” From my experience, people are eager to try it out. At least one PR (sometimes several) is submitted, iterated on, and merged within a matter of a few hours. "

TerryADavis 11y ago

I have a talking SETI. $100,000,000

pella 11y ago

similar : Mozilla "Mentor Bugs If you are looking for a bug with guidance, we maintain a set of bugs that are marked with an assigned mentor (see "Whiteboard" field). The mentor will help you get the necessary information to understand the issue, point out relevant parts of the code to look at, etc. You can browse these bugs on Bugs Ahoy!, but here's a list of unassigned mentor bugs to get you started:" https://wiki.mozilla.org/Mobile/Get_Involved#Mentor_Bugs https://wiki.mozilla.org/Mobile/Get_Involved#Mentor_Bugs Other examples: #easyfix: https://github.com/facebook/flow/labels/easyfix https://github.com/facebook/flow/labels/easyfix #beginner: https://github.com/eslint/eslint/labels/beginner https://github.com/eslint/eslint/labels/beginner #exp:beginner https://github.com/docker/docker/issues?q=is%3Aopen+is%3Aissue+label%3Aexp%2Fbeginner https://github.com/docker/docker/issues?q=is%3Aopen+is%3Aiss...

masklinn 11y ago
> Other examples: Rust has E-easy and E-mentor https://github.com/rust-lang/rust/labels/E-easy https://github.com/rust-lang/rust/labels/E-easy https://github.com/rust-lang/rust/labels/E-mentor https://github.com/rust-lang/rust/labels/E-mentor
larsberg 11y ago
We also try to have good starter bugs on Servo (and its myriad dependencies): http://servo.github.io/servo-starters/ http://servo.github.io/servo-starters/ One of the biggest challenges we have is keeping some around and available! The good ones almost always have an opened PR within 24 hours: https://twitter.com/ServoDev/status/665930502503723008 https://twitter.com/ServoDev/status/665930502503723008 There are a bunch of other benefits to these bugs, including: - There's a lively stream of people setting up the dev environment for the first time, both keeping our instructions up to date and making sure we handle scenarios like slow internet connections, really old versions of Ubuntu or Linux graphics drivers, etc. - Reviewing these bugs is also a good way to help grow contributors from committers into reviewers/maintainers. Most of our challenges with these kinds of bugs are related to GitHub. e.g., you can't "assign" an issue to somebody outside of the project organization, so somebody has to manually label it "Assigned" for our filters to work. Also, you don't get notifications when somebody pushes a new commit to their work branch or rebases, so there's a lot of manual watching of these PRs during the review cycle that sometimes gets dropped (though our myriad GH bots could probably fix this!). Even with the challenges, we love having this kind of bug as a way to bring in more contributors and keep development on the project accessible, and like the author, I'd highly recommend it to other projects.

jedanbik 11y ago

Mentorship in OSS makes everyone involved a little bit better at something, be it following instructions, learning practical tooling, writing clear instructions, justification of process and habits, etc.

MindTwister 11y ago

Huh? Says I posted this 2 hours ago, but I'm pretty sure I posted it yesterday

frostmatthew 11y ago
I believe if dang (and perhaps others) finds a submission that would probably be interesting to a lot of HNers but didn't get much/any traction when initially posted it is "resubmitted" to give it another chance.
mkagenius 11y ago
When you feel anything like that, you should say "dang it" ;)

jondubois 11y ago

There are a lot of ways to contribute that don't involve making pull requests. Identifying and raising issues is a good place to start for someone who is not familiar with the codebase.

Bahamut 11y ago
A caveat to that is that they need to be well-researched before filing issues - otherwise it actually is a negative, especially when a modicum of effort reveals when something actually is a usage issue and not a bug.
- jacquesm 11y ago
  If only that was made easier. And then, of course it also helps if the majority of the bugs you raise are not flagged 'wontfix', which does wonders to encourage further reporting.
- jondubois 11y ago
  I actually don't mind if users report 'issues' which turn out to be their own fault. In some cases this could indicate that a feature in your project isn't intuitive enough. Also I like having as many issues as possible - It creates a knowledge base for your project which people can search through.
mfringel 11y ago
In my experience, raising an issue is followed by "okay, so fix it.", which reduces to a previously noted problem.

batrat 11y ago

This titles man are worst than FB. Why not just "Click here!"?. Or could just copy and paste the title: "A suggestion to Open Source project maintainers"

ant6n 11y ago

As a bit of a nitpick, I find it slightly ironic that this article uses TDD and PR as unexplained abbreviations.

crottypeter 11y ago
TDD is acceptable as it is the top search result for TDD. PR on the other hand ... Acronyms and abbreviations with well defined / well known alternative meanings really bug me. Actually Acronyms and abbreviations bug me full stop.
- ant6n 11y ago
  Well, I googled both, which kinda bugs the flow of reading the article. Abbreviations bug me too.
  - ithinkso 11y ago
    Well, what about RAM, PC and so on? They might be an extreme example but if you are in the 'field' not using abbreviations may actually bug you more. Targeting audience is not an easy task.
    - ant6n 11y ago
      Didn't have to google RAM, PC and so on.
    - yoha 11y ago
      It is often better to use “computer” and “memory”, especially when the distinction between L1/L2/L3/RAM/SSD/HDD is not the main topic.
- rcraggs 11y ago
  The people who will benefit from this article most are people who lead OSS projects, so I don't think it's too much of a problem to use these.
kentcdodds 11y ago

neogodless 11y ago

As a true open-source zero timer, I can't quite figure out what PR means. My gut was "pull request" but it sounds like you're "committing a fix" at this point, so I suppose "push request" might be the answer, but it's an ambiguous pair of letters.

hartator 11y ago
It's pull request, that's git terminoly to merge external code to an existing project.
- diggan 11y ago
  I don't want to nitpick but for a Git beginner (not necessarily you but others reading here), it's important to know that "pull request" is really a Github concept, not a Git one.
  - realityking 11y ago
    Pull request is very much git terminology. Here's the documentation for 'git request-pull': https://git-scm.com/docs/git-request-pull https://git-scm.com/docs/git-request-pull
    - ultrafez 11y ago
      If you're being picky, then I can be picky too: the concept of a "pull request" isn't defined in that manpage, only the command "request-pull" is. A "pull request" is an entity in itself. The command may exist within git, but it's not a part of most people's git workflows. "Pull Request" is a term that's far more commonly attributed-to and associated with tools like GitHub, Gitlab, Bitbucket etc. Did you know that git has the ability to send patches via email, built in [1]? Git has a lot of functions that the majority of people don't use. [1] https://git-scm.com/docs/git-send-email https://git-scm.com/docs/git-send-email
      - realityking 11y ago

yandrypozo 11y ago

This world needs more people like you. Thank you !!

J_Darnley 11y ago

As far as I can tell this information is specific to Github and development on Github. Why is CONTRIBUTING.md important? Its just another file for someone to read alongside COPYING, INSTALL, README, TODO, and perhaps what's in the doc/ directory. And why markdown? Organising and comments are good but people have been trying to get devs to do that for decades and we're still mentioning it. "Add an up-for-grabs label" to what? Where? How will people see this? Adding a githook might be useful on a remote repository but I don't want to run a full test suite every time I commit, ammend a commit, rebase, or otherwise trigger it. What's NPM? Why would anyone use it over a makefile? I would extend my first comment and say this is for javascript projects which use Github and only Github.

deleted 11y ago
[deleted]
tnorthcutt 11y ago
Replace all the language/framework/code-hosting specific terminology with whatever suits you. The attitude and willingness to help newcomers is the point. The author just used his project and experiences as a way to illustrate that point.
wtracy 11y ago
CONTRIBUTING.md is important because it provides an easy entry point for new developers. Out of COPYING, INSTALL, README, and TODO, where do you go to answer that question? Except for TODO, all those files are targeted at end users, not contributors. The choice of Markdown is of course entirely arbitrary. The up-for-grabs label goes in your bug tracker. Then anyone can see it by browsing open bugs. NPM is the package management tool used by Node, not a build tool. I think that Node having its own package manager is ridiculous, but since Node development already requires it, there's no reason for this project to not make full use of it. Outside of using NPM, I don't see anything web-specific, and outside of Githook I don't see anything git-specific. Even Sourceforge gives you a bug tracker!

javajosh 11y ago

Great idea. I would add: if someone tries to do contribute something, but maybe they have a git issue, don't step in and push it yourself. This happened to me on one project, and it bothered me so much that I stopped contributing entirely (which was the right move, it turned out).

amirmc 11y ago

We've a curated set of Pioneer Projects for MirageOS [1], where more established contributors have agreed to act as mentors for newcomers. It's worked really well for us! One of the unexpected benefits was that we could quickly take part in things like Outreachy and GSoC, as we already had a curated list. Reviewing this list every few months has become part of the normal process now. In addition, asking people to act as mentors also gives them a different perspective on the existing code base, especially where things are particularly thorny. [1] https://github.com/mirage/mirage-www/wiki/Pioneer-Projects https://github.com/mirage/mirage-www/wiki/Pioneer-Projects

munchor 11y ago

At elementary OS we have "elementary Drive By Contributors" :) https://launchpad.net/~elementary-driveby https://launchpad.net/~elementary-driveby

thewhitetulip 11y ago
I have found the team to be obstinately stubborn about changing minds

thewhitetulip 11y ago

This is a really nice initiative, when I was starting with open source development I had no idea how to do what we needed to do and almost no project i talked to had any initiative like this where they keep some part of their project open for first timers like me, i had to struggle a lot to get started, it'd be great if more and more influential projects started to use this and if they were a little more open to feedback, of late I have noticed those who manage the project just don't listen to feedback what so ever.

BinaryIdiot 11y ago

Great read. My favorite part is this bullet point: > Use npm scripts so people don’t have to understand or globally install any build tools I do this on every project I work on. In fact, where possible, I completely skip globals entirely (for instance in my msngr.js library it uses Grunt but it executes grunt locally without it being installed globally on the machine). I think it's really important that anyone can go up to a library, pull it down, and start it with little to no further effort. The less friction you can provide a developer the better.

chowes 11y ago
100% agree.. and just as important as ease of starting: ease of finishing. make all of your tests / linters / etc. runnable via a simple npm run. there's overhead in setting this up, but i can remember several times where i have pulled the code down, made my changes, and gave up when trying to figure out how the maintainer wants my code formatted / tested.
peterjmag 11y ago
Agreed! This saved us all kinds of headaches in a large project at my old company (not open source in this case, but still helpful). I left a similar response on Medium before I noticed your comment: https://medium.com/@peterjmag/great-tip-d6fcdec36e13 https://medium.com/@peterjmag/great-tip-d6fcdec36e13

eitland 11y ago

Jenkins has been filling my twitter feed with information for new contributors lately under the hashtag #hacksgiving I think. Edit: Changed "spamming" to "filling" That was meant as a positive thing but I guess I shouldn't have used the word spamming.

deleted 11y ago
[deleted]
eitland 11y ago
Anyone care sharing why I keep getting downvoted for this one? By all means feel free but this one was more than a little puzzling to me : )
- J_Darnley 11y ago
  Probably because you used "spamming". Or you spoke poorly about someone's favourite tool.

jakejake 11y ago

This is really great. I've contributed to lots of projects and it would be nice if maintainers were all this thoughtful. If not actively encouraging people to get involved, it would be nice of maintainers to simply acknowledge or appreciate someone's effort. I've contributed a lot of code and have had vastly different experiences. Sometimes people are excited and accept a PR without question. Some people just ignore PRs. Some people make you feel as though you've just spit in their face. I had one pull request that I thought was reasonable which was met with a ridicule from the maintainer at how useless my idea was (to him). I'm a seasoned programmer with my own projects and a lot of code under my belt but, even knowing how these things work, that one really soured me on his project. I can't imagine if a novice who was excited at their first PR was treated so poorly. If I could suggest anything to maintainers, it would be to simply appreciate that somebody was trying to contribute. If their code doesn't meet your goals or standards, try to still respect that they spent some time on your project.

nartz 11y ago

I think the KEY thing here is that you wrote the tests, that gave someone the 'confidence' to say whether or not they were even on the right track - this is amazing - the tests give exactly the right context for someone to dive into the code.

twic 11y ago

A related effort: https://twitter.com/yourfirstpr https://twitter.com/yourfirstpr

alexc05 11y ago

One thing that he left off his list of things to make contributing successful is seeking up a "docker" box which is ready to go for development. (Or a vagrant file) If the image is set up so it "just works" and has all tools preinstalled, you can be up and running locally in seconds. With NPM scripts, its often possible to run I to problems with node-gyp... Or any other number of cross platform incompatiblities. The docker/vagrant route is a really novel solution I've seen used effectively in other projects.

metasean 11y ago

Along the same lines, I'd encourage everyone, first timers and grey beards alike to check out http://24pullrequests.com/ http://24pullrequests.com/ (they use a 'beginner' instead of 'first-timers-only' as their novice-friendly tag). If you're in the Salt Lake area, also please consider joining us next Saturday [1] or Tuesday, Dec. 15 [2] as we give a little back to the Open Source community! [1] SLC JS Learners - monthly JavaScript Study Group - http://www.meetup.com/SLC-JS-Learners/events/224563977/ http://www.meetup.com/SLC-JS-Learners/events/224563977/ [2] SLC JS Learners - monthly meetup - http://www.meetup.com/SLC-JS-Learners/events/226862778/ http://www.meetup.com/SLC-JS-Learners/events/226862778/

peterjmag 11y ago

I love this. I've been thinking about a very similar issue for a while now, and I'm still trying to organize my thoughts into a blog post or something, but here's the basic idea: Hire more juniors. Or cross-train people from other departments[1]. Doesn't really matter who. But they should be pretty darn close to beginners. Assign a relatively small issue to them. The kind of thing that would only take about an hour for a more senior dev to look in to. Plan more than an hour for the junior. Probably a lot more. Also plan some time for one of those more senior devs. Sit them down next to each other. Point the junior to the readme. Ask the junior to ping / poke / bother the senior every time they hit a roadblock. Every single time. Ask them to be relentlessly persistent. (Not everyone's good at being relentlessly persistent. So encourage them. Create an environment where they feel like they can be relentlessly persistent.) Then leave them alone. Give it a day or two. Watch as interesting things start to happen. Watch as the junior dev learns how to be a better communicator. Watch as they learn how to make problems visible. How to get help. And as an added bonus: how to program. Watch as the senior dev goes insane at first from all the questions. Watch them start to wonder how they can avoid going through this every time somebody needs to touch their code. Watch them remove obstacles. Or at least reduce their number. Watch them automate things. Or speed up things that are already automated. Or improve processes in ways they had never even considered before sitting with the junior. Also watch them learn how to be a better communicator. Do this a few times. Watch for magical things. Code quality improves. Onboarding times plummet. Hiring friction melts away. Teamwork starts... working. Productivity skyrockets. Job satisfaction goes up. Happiness prevails. ----- [1] See also https://twitter.com/patio11/status/657902663686754304 https://twitter.com/patio11/status/657902663686754304