Tuesday, February 12, 2013

Open Source Contribution Etiquette Part II

As the current maintainer of MvvmCross, in the last 7 days I've had contacts via email, GitHub and forum private messaging and Skype from 8 separate individuals who've been looking to contribute.

This is awesome - really it is totally awesome - they've all been lovely and I love it.

Please don't stop!

And please don't have any doubt that I'm very open to people contributing....

If you have any ideas then get in touch via any of the mechanisms on http://slodge.blogspot.co.uk/p/if-youve-got-questions.html - if your contribution is good, you might even get a badge :)


.... please also consider that I'm human, you're not the only user, I'm doing work for free, I care about my work passionately, and that I'm trying to find time to earn a living, write v3 and have a life too....


A few year's back Miguel posted about Open Source Contribution Etiquette

It's a post about trying to make sure that any code you submit as a patch fits well within the project you are contributing to.


As some of you know, I'm not the best at sticking to that rule ... it's not my fault, it's resharper's ... sorry!


However... it's not just about code formatting - there are some other important points that I think it's worth considering when you start contributing to an open source project.

In particular, please do try to have some empathy for the person who is maintaining the project - as Miguel said:
The maintainer is in for the long-haul, and has been working on this code for longer than you have. Chances are, he will keep doing this even after you have long moved into your next project. 

In particular, some of the things I'd ask you to consider are:
  • If the maintainer asks you to contact them via some mechanism then please try to do it - e.g. if they ask you to contact them via GitHub issues instead of Email, then please do not keep sending them emails. And if they then ask a second time, please do not then switch to sending them messages by Skype...
  • Consider that the maintainer owns the project and has final say:
    • They might have plans or dreams which conflict with your immediate requirements - in which case please respect that and find some other way forwards.
    • They should justify their decisions - but they don't deserve to be dragged into drawn out debates on issues - they can ask you to walk away, and you should
    • They can ask you to justify your decisions - and they can drag you into whatever level of justification they choose to - if this is too much, you can, of course, walk away
  • Relationships take time - you can and should always try to be courteous, but respect takes longer to build.
    • The maintainer has probably already earned some respect from you - after all, you want to use and contribute to their work.
    • If this is the first time the maintainer has heard from you, then don't expect respect from them - respect is like that - you have to earn it.
    • Be careful with what you say you are going to deliver - if you criticise a piece of the existing project, say you'll deliver something to fix it, but don't... then don't expect the maintainer to show you much respect when you move on to start criticising something else.
    • Consider that maintainers are often donating large chunks of their time to the project, that they may have other work and/or family matters to attend to; and that they may have recently had to deal with other contributors who did not contribute very well... so those other factors will influence how they deal with your request.
  • Constructive criticism is useful, but constructive action is better - sending criticism of lack of versioning, lack of unit tests, lack of documentation isn't as good as helping make a new build system, a new unit test, or some new documents.
  • The maintainer no doubt has a list of other priorities on his/her list - and those priorities may mean your current contribution is not welcome right now. If that's the case, try to be patient...
  • For whatever reason, if the maintainer says the time's not right for them to accept a contribution, then you should respect that.
  • Solutions to real problems and demonstrable advantages win over possible solutions to possible problems and vague promises of future benefits.
    • If you can show why your changes improve things now, then they can understand why it's worth doing.
    • But if you send them a patch telling them that this will enable something amazing next time, then they have every right to ignore you until next time.
  • Consider that maintainers sometimes want to work on their own project - there are interesting puzzles to solve and things to learn - maintainers love to get inputs but sometimes you also need to give the maintainer space to enjoy their own project too.
  • Regardless of who you are, IMO the best way to push changes into a project is to push small changes - these are easy for both you and the maintainer to qualify, to quality assure and to understand.
  • I understand, though, that sometimes bigger changes are needed, and that sometimes the only way to find out if things will work is to build a prototype - I totally 100% understand that's the way code is sometimes.

    If this is the case and you do need to make bigger changes, consider:
    • If there is any way to make these additions externally to the project - using an add-on pack of some description.
    • If there is some way you can make these change more slowly:
      • Whether you could work on building up a relationship with the maintainer before flooding them with new code
      • Whether you could ask about those changes before making them...
      • Whether you could make those changed by forking
  • Coders (Maintainers and contributors):
    • are all mainly lovely - so you can normally talk before making huge changes.
    • are all mainly ass-holes - we are often stubborn ego-driven psychopaths - we all know that no-one else on the planet understands problemX as well as we do. We all have to live with this - Apple, Microsoft, Facebook would never have happened if Steve, Bill and Mark weren't so special ;)
  • Maintainers have the upper hand and the final say
    • they have put in the hard graft and deserve some additional courteousy as a result
    • if a maintainer says 'no' you can query that once... but if you continue to query a point then the chances are you're going to get nowhere except burning up valuable time and getting deeper entrenched into argument... so stop arguing and find another way forwards independently.
  • Contributors aren't slaves - they have other options:
    • if a maintainer says 'no' you can still publish your changes - that's what the OSS licenses allow for.
    • this may not be perfect - it may not be what you want - but it may be what you need - http://www.youtube.com/watch?v=OagFIQMs1tw
  • No decision is final - if you fork today, then there are always ways of merging forks back together again later.
  • Forking isn't necessarily a bad thing - evolution is good. (IMO)
  • If you really need something then you can sometimes offer to pay for the maintainer to assist - but be very careful about how you ask that question!

Note that this isn't a one-way street - maintainers shouldn't be jerks - see http://lostechies.com/derickbailey/2012/12/14/dear-open-source-project-leader-quit-being-a-jerk/ for some very sage advice for maintainers!


Note also that you shouldn't listen to me....

I've broken the etiquette rules and been very, very naughty in my open source contributions.

If you don't believe me, take a look at what I did what Resharper did to MonoTouch.Dialog within MvvmCross!


Now, back to the code....

F5 ;)

No comments:

Post a Comment