First version of the mechanics of contributing article, addresses #74 #117
Conversation
| This is great, Johannes. I'm really looking forward to reviewing this content. I am taking an extended weekend to camp with my family so time is tight for me right now, but I may be able to take a look next week. |
MaineC left a comment
MaineC left a comment There was a problem hiding this comment.
That's a really nice text going over the mechanics of contributing. I've left "a few" comments :)
| The basic point is that aside of reliability in collaboration, continued presence the effect of water cooler discussions and food/drink consumption is quite impressive... | ||
| ] | ||
| | ||
| Especially in the case of larger distances between you and the host teams, e.g. multiple time zones difference as in San Francisco, USA (PDT) and Berlin, Germany (CEST), you will need to actively consider this and explicitly manage your and their expectations on reaction times. |
There was a problem hiding this comment.
I'd go the other way around here: Explain why expectation management wrt. to reaction time is important even with people in the same physical location - and after that mention that clearly this is even more important when we are talking about people in different time zones.
Too often I've seen mis-matched expectations wrt. turnaround times cause frustration and impatience. Once this topic was talked about, even a few days were ok. Often what also helped was receiving a reaction like "I'll look into it, I won't get to it in the next few days though" (much like @rrrutledge did with your PR here actually ;) )
| ### Lead times | ||
| | ||
| One key difference is the turn-around time. | ||
| You're coming to a new (host) team on every first contribution and thus you'll need to get to know their approach, i.e. their development, reviews and deployment, etc. processes. |
There was a problem hiding this comment.
What about getting to know their code-base ;)
There was a problem hiding this comment.
Um, yes indeed, very much so xD. Care to add a commit suggestion for this that I can merge?
lenucksi left a comment
lenucksi left a comment There was a problem hiding this comment.
Thanks for the detailed review, I also added a "few" replies.
And committed the nice commit suggestions, thanks for them! :)
| ### Lead times | ||
| | ||
| One key difference is the turn-around time. | ||
| You're coming to a new (host) team on every first contribution and thus you'll need to get to know their approach, i.e. their development, reviews and deployment, etc. processes. |
There was a problem hiding this comment.
Um, yes indeed, very much so xD. Care to add a commit suggestion for this that I can merge?
| This challenge is a frequent challenge and many team relationships suffered from not handling the fit in advance. | ||
| | ||
| Make yourself and the host team happy (and possibly even save some work) by getting agreement from the host team on the user/technical design of the contribution _before_ submitting a pull request. | ||
| You'll have to understand how the host team would like you to reach out for this - sometimes they have regular design discussions in person or via chat/voice/video conferences, some hand in design discussion / extension proposal documents for collective discussion and review, some work with feature requests, etc. |
There was a problem hiding this comment.
You are very right here.
I'll try to rephrase things here. I'd also add that having regular non-written conversations might be totally ok, however that time-zone-based participation limitations need to be considered for inclusivity and that the final goal needs to be having everything written & linkable/searchable.
Side note: an interesting approach are some of the meetings that OpenZFS holds are recorded and put online on Youtube - generating possibly searchable subtitles. Pure text is easier though...
| | ||
| Make yourself and the host team happy (and possibly even save some work) by getting agreement from the host team on the user/technical design of the contribution _before_ submitting a pull request. | ||
| You'll have to understand how the host team would like you to reach out for this - sometimes they have regular design discussions in person or via chat/voice/video conferences, some hand in design discussion / extension proposal documents for collective discussion and review, some work with feature requests, etc. | ||
| Ask a trusted committer about how to best discuss your proposal. |
There was a problem hiding this comment.
I agree, would you care to make commit suggestion to change that line to that version? (Otherwise I'll do that)
Co-Authored-By: Isabel Drost-Fromm <isabel.drostfromm@gmail.com>
rrrutledge left a comment
rrrutledge left a comment There was a problem hiding this comment.
Oh sorry I never clicked "submit" to this review I did last week.
| | ||
| Try to peruse their documentation, the conversation archives and code artifacts from the host team to unblock yourself - this is pretty much similar to the situation you and likely most people find yourself in when using one of the popular OSS projects. | ||
| | ||
| Much like in Open Source projects, make use of the advantage to be able to directly ask the host team if, even after trying to unblock yourself, things went nowhere. The questions you ask and the answers you receive will help others coming after you solve the same issues - so make sure that your communication ends up in a searchable archive that is closely linked to the project itself. |
There was a problem hiding this comment.
make sure that your communication ends up in a searchable archive
I think that this is the responsibility of the Host team instead of the Contributor. The Host team should encourage questions to go to a location where they can be searched later. The Contributor should just ask questions wherever the Host team encourages them to ask them.
Co-Authored-By: rrrutledge <rrrutledge@users.noreply.github.com> Co-Authored-By: Isabel Drost-Fromm <isabel.drostfromm@gmail.com>
…nerSourceLearningPath into 74-mechanics-of-contributing
lenucksi left a comment
lenucksi left a comment There was a problem hiding this comment.
Added a few comments, accepted a bunch of commit suggestions and added a few commit suggestions myself.
Also a few lines of new commits for longer parts are in.
rrrutledge left a comment
rrrutledge left a comment There was a problem hiding this comment.
Excited to see the progress on this article!
| Start early enough so that your work is available for you to leverage at the time you need it. | ||
| It's better to add more slack time initially - you'll get a feeling about the turn-around times once you work with the host team. | ||
| Often, you will notice a reduction in turn-around time per host team after making a few successful contributions to that host team. | ||
| This is effect can be observed with Open Source as well, you can read more about it [here](https://doi.org/10.1109/MS.2013.95). |
There was a problem hiding this comment.
Should we link to a document that is not publicly-available?
There was a problem hiding this comment.
I would leave it in and maybe add a note stating the access limitations. Various corporations actually do have access to the usual subscription systems via their research arms - and it should be accessible to the public from public university libraries I'd think.
Co-Authored-By: rrrutledge <rrrutledge@users.noreply.github.com>
lenucksi left a comment
lenucksi left a comment There was a problem hiding this comment.
Added a few comments on the feedback and a new commit suggestion.
| Start early enough so that your work is available for you to leverage at the time you need it. | ||
| It's better to add more slack time initially - you'll get a feeling about the turn-around times once you work with the host team. | ||
| Often, you will notice a reduction in turn-around time per host team after making a few successful contributions to that host team. | ||
| This is effect can be observed with Open Source as well, you can read more about it [here](https://doi.org/10.1109/MS.2013.95). |
There was a problem hiding this comment.
I would leave it in and maybe add a note stating the access limitations. Various corporations actually do have access to the usual subscription systems via their research arms - and it should be accessible to the public from public university libraries I'd think.
rrrutledge left a comment
rrrutledge left a comment There was a problem hiding this comment.
Thanks for the updates!
| Start early enough so that your work is available for you to leverage at the time you need it. | ||
| It's better to add more slack time initially - you'll get a feeling about the turn-around times once you work with the host team. | ||
| Often, you will notice a reduction in turn-around time per host team after making a few successful contributions to that host team. | ||
| This is effect can be observed with Open Source as well, you can read more about it [here](https://doi.org/10.1109/MS.2013.95). |
rrrutledge left a comment
rrrutledge left a comment There was a problem hiding this comment.
Thanks for this work, Johannes!
rrrutledge left a comment
rrrutledge left a comment There was a problem hiding this comment.
Looks good to me. Thanks, Johannes!
Co-Authored-By: Isabel Drost-Fromm <isabel.drostfromm@gmail.com>
| Yay! |
Clean up the mis-merges introduced by #117.
3 participants
This pull request contains a first version of the "The Mechanics of Contributing" article according to the outline document.
I've used a more interactive, reader focussed writing style this time.
Looking for feedback if it's too colloquial in style.