From ff5ca1afc7dc2556f19173474e88f9de7146d1ba Mon Sep 17 00:00:00 2001 From: Johannes Tigges Date: Fri, 16 Aug 2019 17:20:42 +0200 Subject: [PATCH 01/12] First version of the mechanics of contributing article, fixes #74 --- contributor/04-mechanics-of-contributing.md | 125 ++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 contributor/04-mechanics-of-contributing.md diff --git a/contributor/04-mechanics-of-contributing.md b/contributor/04-mechanics-of-contributing.md new file mode 100644 index 00000000..0728ae0d --- /dev/null +++ b/contributor/04-mechanics-of-contributing.md @@ -0,0 +1,125 @@ +# Draft comments + +## Video playbook outline + +What are the nuts and bolts of advice to follow when acting as an InnerSource Contributor? This segment describes the hands-on things to do to make your contribution a success. We'll give practical tips to leverage when preparing to work on a contribution, during development, and also in the pull request. + +## Outline doc + +See [Outline Section](https://github.com/InnerSourceCommons/InnerSourceLearningPath/blob/master/contributor/outline.md#mechanics-of-contributing) + +# Article + +You are ready to start contributing to other teams projects/repos or look forward to reduce your blockers by not playing the big-cheese game but by collaborating? +Please consider reading this section beforehand as it will give you practical advice and informs you about gotchas to remember when making an InnerSource contribution. This will hopefully enable you and the host team to have as pleasant an experience as possible setting the foundation for more contributions and great collaboration. + +This article is separated into the three steps you will likely experience + +- Soliciting your contribution opportunity and preparing to work on it +- Actually creating the contribution +- Polishing and wrapping the gift nicely and presenting it to the host team. + +If your contribution is larger, you'll possibly go through (some) these steps repeatedly as you iterate towards your common goal. +It is very likely that as you do this everything will feel more and more naturally - maybe you'll even wonder why you were doing anything else before. + +## Preparing to work + +### 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. +Even if you are coming back after a while the teams' ways and members might have changed - take your time as you would to catch up with a friend you haven't seen in a while and whom you are visiting now. + +Thus: Please give yourself enough lead time. +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. +If you end with too much there surely will be a great way to make use of the time, be it some work on your side, the quirky bug or improvement opportunity you found while making your initial contribution or possibly even a nice chat over coffee, beers in case of personal availability or whatever topic in case of distributed projects. + +[EDITOR NOTE: There was actually a paper on how trust is build up on remote/asynchronous collaboration. Maybe I'll find that again. +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. + +### Avoiding rejection + +You've got this really large feature or larger rewrite in mind that would be totally great and add real value that you would like to donate? +Excellent! +Wouldn't it be horrible if all your work would be wasted because the host team is maybe already building something very similar, is planning to depreciate the part of the software you are trying to extend or even does not see what you are proposing to be a fit for their project? +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. +Ask a trusted committer about how to best discuss your proposal. + +This type of high-level, up-front agreement early will save time in rework or rejection of your pull request down the road. + +## Creating the pull request + +### Communication and unblocking yourself + +Great, you've made yourself familiar with the host teams approach and they are looking forward to receive your pull request. +Which gotchas are there waiting for you now? + +First, you'll be in less direct contact with them and second you aren't expected to be as knowledgeable and proficient as you might be on the full-time projects that your team owns. +How can you now deal with this the best? + +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. + +However, this time you've got the advantage to be able to directly ask the host team if, even after trying to unblock yourself, things went nowhere. (That's an approach that works with many OSS projects as well!) +It doesn't do either side any good for you to spin forever on a problem that could be resolved in a few-minute conversation with someone more knowledgeable about the project. +It's OK to ask for help. + +There's one key difference though, bringing advantage to you and other people in the future: +In almost all cases you should prefer the projects' official communication channels - this can be a mailing list, a chat room, the issue tracker or something similar depending on the purpose of having a more synchronous or asynchronous way of interacting or the varying needs for structure in the communication. +All of those usually have in common that they are text-based, archived, searchable and linkable - this means your question and the answer will be written down. +This way you could benefit from this passively documented knowledge on your search and will help future contributors to have the same advantage. +Imagine what would be needed for realizing this benefit by just walking by or calling a trusted committer on the project or even in a group call. + +Did you on your way of trying to unblock yourself find that you were missing documentation or found parts of it to be wrong or out-of-date and had to figure this out for yourself now? +Often projects are happy to receive additions, updates or corrections for their existing documentation as well - you've just found another opportunity to contribute! +(Or just politely provide them with feedback on your experience and what would have helped you.) + +### Crafting the code + +We all have our preferences and opinions on code style, indentation, etc. +The home that the host team lives in will have them as well, individual wallpaper, decoration and hangings incl. +Try to adapt and match those preferences even if it's not what you would normally do and even if it is not specified in the projects' `CONTRIBUTING.md`. +If you are unsure you can always ask politely, nevertheless a guest contribution for a feature or bug fix is not the time to introduce a new way of structuring or formatting project code. + +## Submitting the pull request + +You've completed all the essential work, figured out all the quirks of the problem and the project you are contributing to, the time you've planned for the new feature to be used comes nearer and you want to make sure your contribution gets merged in as fast and smooth as possible? + +Here's what you can do to make reviewing and merging as easy as possible for the the trusted committer and the host team. +(This might actually be pretty similar to what you might already be doing on your own project to get your changes accepted - if that's the case: great, this is going to come natural to you!) + +### Testing and automation + +The basic point here is to enable the trusted committer to validate the contribution without your presence and to ensure easy maintainability. +To achieve this do the following: + +- Add tests for your code contribution so that validating the function of your contribution by others works well, even after some time when you work in other projects or might have stopped to contribute to this project. + - Often projects will use automated checks against pull request using those tests and the level of code coverage. Try to meet the criteria these test enforce. +- Many projects will provide project build and validations scripts to enable you to locally test your changes. + - Use those to ensure that your contribution works as well as possible before opening a pull request. + - Having to review defect pull requests with easy-to-fix errors often bugs trusted committers. They will not fix your code but ask you to do so. This might create more round-trips and slow the merge if there's unnecessary errors. + - No one's perfect though. Try your best, use the prepared validation scripts if there are any and give it your best shot with a pull request! +- Don't forget your own project that triggered your contribution in the first place. Build a modified build of the shared project with your changes and try it out in your own project that consumes it. + +### Documentation and reviewability + +You'll want to ensure that your pull request includes any documentation updates are relevant to your changes. +Should the documentation live in a different place, make sure you add them there and link to them in the pull request. + +To make the actual code review as easy as possible for the trusted committer or other persons reviewing it, try to follow these hints: + +- Be sure that your pull request includes just the relevant changes for the issue you're completing. +- Try to avoid super-large commits, commits with unclear commit messages, gazillions of files, incoherent changes (e.g. touching multiple topics). +- Provide a clear description what this pull request changes, why it does so and which issue and possible design documents (if there were any) it refers to. +- If there is anything uncommon or unexpected in the pull request highlight it and provide an explanation. This will make it easier to reason about and solve potential blocking questions the reviewer might have during the review. + - The same goes for place where you were unsure in the implementation or your approach - highlight it and ask for insight. + - Be civil and expect civility from the trusted committers' review. +- Making pull requests too broad and large makes them more difficult to review and longer before they're accepted. + - If you have a larger feature you are contributing it often helps to split it in multiple pull request that get submitted, reviewed and accepted sequentially. + - You can still bind them together with an issue the are referring to. From 24e9a296bcf02c93a60c3f1bad4a63d76c90eb26 Mon Sep 17 00:00:00 2001 From: Johannes Tigges Date: Thu, 22 Aug 2019 20:39:02 +0200 Subject: [PATCH 02/12] Apply suggestions from code review Co-Authored-By: Isabel Drost-Fromm --- contributor/04-mechanics-of-contributing.md | 22 ++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/contributor/04-mechanics-of-contributing.md b/contributor/04-mechanics-of-contributing.md index 0728ae0d..9594e3bc 100644 --- a/contributor/04-mechanics-of-contributing.md +++ b/contributor/04-mechanics-of-contributing.md @@ -45,10 +45,10 @@ Especially in the case of larger distances between you and the host teams, e.g. You've got this really large feature or larger rewrite in mind that would be totally great and add real value that you would like to donate? Excellent! -Wouldn't it be horrible if all your work would be wasted because the host team is maybe already building something very similar, is planning to depreciate the part of the software you are trying to extend or even does not see what you are proposing to be a fit for their project? +Wouldn't it be horrible if all your work would be wasted because the host team is maybe already building something very similar, is planning to deprecate the part of the software you are trying to extend or even does not see what you are proposing to be a fit for their project? 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. +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_ working on the changes and 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. @@ -58,7 +58,7 @@ This type of high-level, up-front agreement early will save time in rework or re ### Communication and unblocking yourself -Great, you've made yourself familiar with the host teams approach and they are looking forward to receive your pull request. +Great, you've made yourself familiar with the host team's approach and they are looking forward to receive your pull request. Which gotchas are there waiting for you now? First, you'll be in less direct contact with them and second you aren't expected to be as knowledgeable and proficient as you might be on the full-time projects that your team owns. @@ -66,13 +66,13 @@ How can you now deal with this the best? 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. -However, this time you've got the advantage to be able to directly ask the host team if, even after trying to unblock yourself, things went nowhere. (That's an approach that works with many OSS projects as well!) +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. It doesn't do either side any good for you to spin forever on a problem that could be resolved in a few-minute conversation with someone more knowledgeable about the project. It's OK to ask for help. There's one key difference though, bringing advantage to you and other people in the future: In almost all cases you should prefer the projects' official communication channels - this can be a mailing list, a chat room, the issue tracker or something similar depending on the purpose of having a more synchronous or asynchronous way of interacting or the varying needs for structure in the communication. -All of those usually have in common that they are text-based, archived, searchable and linkable - this means your question and the answer will be written down. +All of those usually have in common that they are text-based, archived, searchable and come with stable links - this means your question and the answer will be written down, references you link in those answers will also be kept reachable. This way you could benefit from this passively documented knowledge on your search and will help future contributors to have the same advantage. Imagine what would be needed for realizing this benefit by just walking by or calling a trusted committer on the project or even in a group call. @@ -100,8 +100,8 @@ The basic point here is to enable the trusted committer to validate the contribu To achieve this do the following: - Add tests for your code contribution so that validating the function of your contribution by others works well, even after some time when you work in other projects or might have stopped to contribute to this project. - - Often projects will use automated checks against pull request using those tests and the level of code coverage. Try to meet the criteria these test enforce. -- Many projects will provide project build and validations scripts to enable you to locally test your changes. + - Often projects will use automated checks against pull requests using those tests and the level of code coverage. Try to meet the criteria these tests enforce. +- Many projects will provide project build and validation scripts that enable you to locally test your changes. - Use those to ensure that your contribution works as well as possible before opening a pull request. - Having to review defect pull requests with easy-to-fix errors often bugs trusted committers. They will not fix your code but ask you to do so. This might create more round-trips and slow the merge if there's unnecessary errors. - No one's perfect though. Try your best, use the prepared validation scripts if there are any and give it your best shot with a pull request! @@ -109,7 +109,7 @@ To achieve this do the following: ### Documentation and reviewability -You'll want to ensure that your pull request includes any documentation updates are relevant to your changes. +You'll want to ensure that your pull request includes any documentation updates that are relevant to your changes. Should the documentation live in a different place, make sure you add them there and link to them in the pull request. To make the actual code review as easy as possible for the trusted committer or other persons reviewing it, try to follow these hints: @@ -120,6 +120,6 @@ To make the actual code review as easy as possible for the trusted committer or - If there is anything uncommon or unexpected in the pull request highlight it and provide an explanation. This will make it easier to reason about and solve potential blocking questions the reviewer might have during the review. - The same goes for place where you were unsure in the implementation or your approach - highlight it and ask for insight. - Be civil and expect civility from the trusted committers' review. -- Making pull requests too broad and large makes them more difficult to review and longer before they're accepted. - - If you have a larger feature you are contributing it often helps to split it in multiple pull request that get submitted, reviewed and accepted sequentially. - - You can still bind them together with an issue the are referring to. +- Making pull requests too broad and large makes them more difficult to review so it will take much longer before they're accepted. + - If you have a larger feature you are contributing it often helps to split it in multiple pull requests that get submitted, reviewed and accepted sequentially. + - You can still bind them together with an issue that you are referring to. From 5ef800f9f35165b11adcd22b280c74e807bc4b6c Mon Sep 17 00:00:00 2001 From: Johannes Tigges Date: Mon, 16 Sep 2019 16:56:42 +0200 Subject: [PATCH 03/12] Apply suggestions from code review Co-Authored-By: rrrutledge Co-Authored-By: Isabel Drost-Fromm --- contributor/04-mechanics-of-contributing.md | 46 +++++++++++++++------ 1 file changed, 33 insertions(+), 13 deletions(-) diff --git a/contributor/04-mechanics-of-contributing.md b/contributor/04-mechanics-of-contributing.md index 9594e3bc..ae7d586d 100644 --- a/contributor/04-mechanics-of-contributing.md +++ b/contributor/04-mechanics-of-contributing.md @@ -10,8 +10,9 @@ See [Outline Section](https://github.com/InnerSourceCommons/InnerSourceLearningP # Article -You are ready to start contributing to other teams projects/repos or look forward to reduce your blockers by not playing the big-cheese game but by collaborating? -Please consider reading this section beforehand as it will give you practical advice and informs you about gotchas to remember when making an InnerSource contribution. This will hopefully enable you and the host team to have as pleasant an experience as possible setting the foundation for more contributions and great collaboration. +Are you ready to start contributing to other teams projects/repos? +Do you look forward to reducing your blockers not by management escalation but by collaboration? +This section gives practical advice and highlights gotchas to remember when making an InnerSource contribution. It enables you and the host team to have as pleasant an experience as possible, setting the foundation for more contributions and great collaboration. This article is separated into the three steps you will likely experience @@ -27,10 +28,14 @@ It is very likely that as you do this everything will feel more and more natural ### 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. -Even if you are coming back after a while the teams' ways and members might have changed - take your time as you would to catch up with a friend you haven't seen in a while and whom you are visiting now. - -Thus: Please give yourself enough lead time. +With every first time contribution you are coming to a new (host) team. +As a result, you'll need to get to know their code-base and the technology used, but also their preferred development environment (think test framework, build system). +Even in cases where this type of tooling is standardized each team will have developed some individual peculiarities. +In addition to the technical side, you may be faced with differences in communication, think code-reviews. +Even if you are coming back after a while the teams' ways and members might have changed. +Take your time as you would to catch up with a friend you haven't seen in a while and whom you are visiting now. + +Give yourself enough lead time. 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. If you end with too much there surely will be a great way to make use of the time, be it some work on your side, the quirky bug or improvement opportunity you found while making your initial contribution or possibly even a nice chat over coffee, beers in case of personal availability or whatever topic in case of distributed projects. @@ -40,13 +45,25 @@ The basic point is that aside of reliability in collaboration, continued presenc ] 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. +### Building trust + +InnerSource puts huge weight on written communication - in particular when it comes to project decisions. +Does that imply that in-person communication is forbidden? + +Clearly not: Where written communication shines when it comes to archiving and searchability, in-person communication shines when it comes to communication bandwidth. +Try to make time to meet the people behind the names. If possible, try to meet them over your favorite beverage or some food. +When you're able to hear people speak, when you know their idiosyncrasies remote collaboration will become easier. +[EDITOR NOTE: There was actually a paper on how trust is build up on remote/asynchronous collaboration. Maybe I'll find that again. +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... +] ### Avoiding rejection -You've got this really large feature or larger rewrite in mind that would be totally great and add real value that you would like to donate? +Do you have a large feature that you want to contribute? Excellent! -Wouldn't it be horrible if all your work would be wasted because the host team is maybe already building something very similar, is planning to deprecate the part of the software you are trying to extend or even does not see what you are proposing to be a fit for their project? -This challenge is a frequent challenge and many team relationships suffered from not handling the fit in advance. +Wouldn't it be horrible if all your work would be wasted? +That can happen when the host team is already building something very similar, is planning to deprecate the the software, or does not see what you are proposing to be a fit for their project? +This challenge is a frequent challenge and many team relationships suffered from not agreeing in advance that a contribution is a good fit. 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_ working on the changes and 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. @@ -64,9 +81,12 @@ Which gotchas are there waiting for you now? First, you'll be in less direct contact with them and second you aren't expected to be as knowledgeable and proficient as you might be on the full-time projects that your team owns. How can you now deal with this the best? -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. +Try to peruse their documentation, the conversation archives and code artifacts from the host team to unblock yourself. +This is 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. +Much like in Open Source projects, ask the host team if things are going nowhere even after trying to unblock yourself. +The questions you ask and the answers you receive will help others coming after you solve the same issues. +Make sure that your communication ends up in a searchable archive that is closely linked to the project itself. It doesn't do either side any good for you to spin forever on a problem that could be resolved in a few-minute conversation with someone more knowledgeable about the project. It's OK to ask for help. @@ -76,14 +96,14 @@ All of those usually have in common that they are text-based, archived, searchab This way you could benefit from this passively documented knowledge on your search and will help future contributors to have the same advantage. Imagine what would be needed for realizing this benefit by just walking by or calling a trusted committer on the project or even in a group call. -Did you on your way of trying to unblock yourself find that you were missing documentation or found parts of it to be wrong or out-of-date and had to figure this out for yourself now? +As you work if you find missing (or out-of-date) documentation, do a favor to the next Contributor and update it with what you've discovered. Often projects are happy to receive additions, updates or corrections for their existing documentation as well - you've just found another opportunity to contribute! (Or just politely provide them with feedback on your experience and what would have helped you.) ### Crafting the code We all have our preferences and opinions on code style, indentation, etc. -The home that the host team lives in will have them as well, individual wallpaper, decoration and hangings incl. +The host team's project has them as well. Try to adapt and match those preferences even if it's not what you would normally do and even if it is not specified in the projects' `CONTRIBUTING.md`. If you are unsure you can always ask politely, nevertheless a guest contribution for a feature or bug fix is not the time to introduce a new way of structuring or formatting project code. From 2f0b3a887027a3f37ca3605359c1271d16cccd52 Mon Sep 17 00:00:00 2001 From: Johannes Tigges Date: Mon, 16 Sep 2019 17:22:32 +0200 Subject: [PATCH 04/12] Add article on lead-time reduction vs. trust. --- contributor/04-mechanics-of-contributing.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/contributor/04-mechanics-of-contributing.md b/contributor/04-mechanics-of-contributing.md index 0728ae0d..861889db 100644 --- a/contributor/04-mechanics-of-contributing.md +++ b/contributor/04-mechanics-of-contributing.md @@ -33,6 +33,8 @@ Even if you are coming back after a while the teams' ways and members might have Thus: Please give yourself enough lead time. 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). If you end with too much there surely will be a great way to make use of the time, be it some work on your side, the quirky bug or improvement opportunity you found while making your initial contribution or possibly even a nice chat over coffee, beers in case of personal availability or whatever topic in case of distributed projects. [EDITOR NOTE: There was actually a paper on how trust is build up on remote/asynchronous collaboration. Maybe I'll find that again. From 932d256d066b58a880530dcfc9966b8e66cca478 Mon Sep 17 00:00:00 2001 From: Johannes Tigges Date: Mon, 16 Sep 2019 17:40:08 +0200 Subject: [PATCH 05/12] Addressed the design discussion conversation - this one: https://github.com/InnerSourceCommons/InnerSourceLearningPath/pull/117/files#r315649853 --- contributor/04-mechanics-of-contributing.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/contributor/04-mechanics-of-contributing.md b/contributor/04-mechanics-of-contributing.md index b0d18b43..69f7fc03 100644 --- a/contributor/04-mechanics-of-contributing.md +++ b/contributor/04-mechanics-of-contributing.md @@ -68,8 +68,11 @@ That can happen when the host team is already building something very similar, i This challenge is a frequent challenge and many team relationships suffered from not agreeing in advance that a contribution is a good fit. 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_ working on the changes and 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. +You'll have to understand how the host team would like you to reach out for this. +It's best to ask a trusted committer about how to best discuss your proposal. + +It is time-and-again-proven wisdom from the Open Source arena that, if you get to select how to discuss your proposal you should try to select a written way. +Ideally one whose artifacts are public, searchable and perma-linkable to enable referencing your proposal in later discussions on this future contribution or other contributions to come - by you or others. This type of high-level, up-front agreement early will save time in rework or rejection of your pull request down the road. From 59829a9d3889756aeaee1aa8c6903506f49f4a6c Mon Sep 17 00:00:00 2001 From: Johannes Tigges Date: Tue, 17 Sep 2019 16:01:11 +0200 Subject: [PATCH 06/12] Update contributor/04-mechanics-of-contributing.md Co-Authored-By: rrrutledge --- contributor/04-mechanics-of-contributing.md | 1 - 1 file changed, 1 deletion(-) diff --git a/contributor/04-mechanics-of-contributing.md b/contributor/04-mechanics-of-contributing.md index 69f7fc03..df8f3983 100644 --- a/contributor/04-mechanics-of-contributing.md +++ b/contributor/04-mechanics-of-contributing.md @@ -40,7 +40,6 @@ Start early enough so that your work is available for you to leverage at the tim 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). -If you end with too much there surely will be a great way to make use of the time, be it some work on your side, the quirky bug or improvement opportunity you found while making your initial contribution or possibly even a nice chat over coffee, beers in case of personal availability or whatever topic in case of distributed projects. [EDITOR NOTE: There was actually a paper on how trust is build up on remote/asynchronous collaboration. Maybe I'll find that again. 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... From 302222222ced99f91df8781ee8067d69fb88385b Mon Sep 17 00:00:00 2001 From: Johannes Tigges Date: Thu, 19 Sep 2019 15:35:58 +0200 Subject: [PATCH 07/12] Update contributor/04-mechanics-of-contributing.md --- contributor/04-mechanics-of-contributing.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/contributor/04-mechanics-of-contributing.md b/contributor/04-mechanics-of-contributing.md index df8f3983..1033c72c 100644 --- a/contributor/04-mechanics-of-contributing.md +++ b/contributor/04-mechanics-of-contributing.md @@ -45,7 +45,14 @@ This is effect can be observed with Open Source as well, you can read more about 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. +### Expectation management +In your classic teams everyone had an idea of the expectable lead times. +Within an InnerSource context this might not be the case, either due to large time-zone differences (e.g. Seattle, USA with PDT vs Berlin, Germany with CEST) or you not being available full-time as with your original team even if they are in the same physical location as you are. +Thus, to prevent frustration on both sides, impatience and other non-trust-building effects you'll need to explicitly do expectations management with regards to your expected reaction times. +One approach be to just quickly react with a "I'll look into it, I won't get to it in the next few days though" to a Trusted Committer's feedback if you know that you'll only be able to come back to them in a few days. +Ideally you can provide them with a rough estimate when you likely will have time to take a look at their input. +Doing so builds trust by reliability even over non-physical contact, longer distance or otherwise asynchronous media. +Established trust will allow you overcome uncertainty bumps in the collaborative road ahead of you. ### Building trust InnerSource puts huge weight on written communication - in particular when it comes to project decisions. From a2a629b9a3f60f659546c0efd3c306229d8de6fb Mon Sep 17 00:00:00 2001 From: Johannes Tigges Date: Sat, 21 Sep 2019 18:10:56 +0200 Subject: [PATCH 08/12] Apply suggestions from code review --- contributor/04-mechanics-of-contributing.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/contributor/04-mechanics-of-contributing.md b/contributor/04-mechanics-of-contributing.md index 1033c72c..2ea151c7 100644 --- a/contributor/04-mechanics-of-contributing.md +++ b/contributor/04-mechanics-of-contributing.md @@ -153,4 +153,8 @@ To make the actual code review as easy as possible for the trusted committer or - Be civil and expect civility from the trusted committers' review. - Making pull requests too broad and large makes them more difficult to review so it will take much longer before they're accepted. - If you have a larger feature you are contributing it often helps to split it in multiple pull requests that get submitted, reviewed and accepted sequentially. + - Some tools also have Draft / WIP pull request functionality that you can use to explicitly mark unfinished and non-polished work and still get early feedback from your host team's trusted committers. + - This allows you to ensure you are going down a path that your host team is happy to merge once it's done, adhering to the "release early, release often" idea in a way. + - The host teams' responsibility is to create an atmosphere where sharing and discussing not-totally-polished work is possible and welcome. If you can't fail safe, you can't innovate and collaborate becomes very hard. + - Try to balance between asking for review early and providing meaningful changes to review. - You can still bind them together with an issue that you are referring to. From cf107c2eec262dfaf4021463b87dc6b9583d7800 Mon Sep 17 00:00:00 2001 From: Johannes Tigges Date: Mon, 30 Sep 2019 16:58:06 +0200 Subject: [PATCH 09/12] Moved the access restricted paper to a references section. --- contributor/04-mechanics-of-contributing.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/contributor/04-mechanics-of-contributing.md b/contributor/04-mechanics-of-contributing.md index 2ea151c7..3cd577d0 100644 --- a/contributor/04-mechanics-of-contributing.md +++ b/contributor/04-mechanics-of-contributing.md @@ -39,7 +39,7 @@ Give yourself enough lead time. 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). +This is effect can be observed with Open Source as well, you can read more about it [here](#buildup-of-trust-through-collaboration). [EDITOR NOTE: There was actually a paper on how trust is build up on remote/asynchronous collaboration. Maybe I'll find that again. 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... @@ -157,4 +157,10 @@ To make the actual code review as easy as possible for the trusted committer or - This allows you to ensure you are going down a path that your host team is happy to merge once it's done, adhering to the "release early, release often" idea in a way. - The host teams' responsibility is to create an atmosphere where sharing and discussing not-totally-polished work is possible and welcome. If you can't fail safe, you can't innovate and collaborate becomes very hard. - Try to balance between asking for review early and providing meaningful changes to review. - - You can still bind them together with an issue that you are referring to. + - You can still bind them together with an issue that you are referring to. + +## Additional articles +Some of these resources might be hidden behind paywalls. +Sometimes your employer has a subscription enabling access, otherwise public university libraries often allow access for guests, too. + +### [Buildup of trust through collaboration](https://doi.org/10.1109/MS.2013.95) From 8705f0ef36a3068c0a41e67762de3f6cc28602a1 Mon Sep 17 00:00:00 2001 From: Johannes Tigges Date: Sat, 5 Oct 2019 18:42:32 +0200 Subject: [PATCH 10/12] Update contributor/04-mechanics-of-contributing.md --- contributor/04-mechanics-of-contributing.md | 1 - 1 file changed, 1 deletion(-) diff --git a/contributor/04-mechanics-of-contributing.md b/contributor/04-mechanics-of-contributing.md index 3cd577d0..cc706184 100644 --- a/contributor/04-mechanics-of-contributing.md +++ b/contributor/04-mechanics-of-contributing.md @@ -105,7 +105,6 @@ There's one key difference though, bringing advantage to you and other people in In almost all cases you should prefer the projects' official communication channels - this can be a mailing list, a chat room, the issue tracker or something similar depending on the purpose of having a more synchronous or asynchronous way of interacting or the varying needs for structure in the communication. All of those usually have in common that they are text-based, archived, searchable and come with stable links - this means your question and the answer will be written down, references you link in those answers will also be kept reachable. This way you could benefit from this passively documented knowledge on your search and will help future contributors to have the same advantage. -Imagine what would be needed for realizing this benefit by just walking by or calling a trusted committer on the project or even in a group call. As you work if you find missing (or out-of-date) documentation, do a favor to the next Contributor and update it with what you've discovered. Often projects are happy to receive additions, updates or corrections for their existing documentation as well - you've just found another opportunity to contribute! From 5dfcf64ed28861e144de975943304614ada8b89f Mon Sep 17 00:00:00 2001 From: rrrutledge Date: Sat, 5 Oct 2019 16:39:22 -0700 Subject: [PATCH 11/12] typo/formatting --- contributor/04-mechanics-of-contributing.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/contributor/04-mechanics-of-contributing.md b/contributor/04-mechanics-of-contributing.md index cc706184..a4b3c00d 100644 --- a/contributor/04-mechanics-of-contributing.md +++ b/contributor/04-mechanics-of-contributing.md @@ -20,8 +20,8 @@ This article is separated into the three steps you will likely experience - Actually creating the contribution - Polishing and wrapping the gift nicely and presenting it to the host team. -If your contribution is larger, you'll possibly go through (some) these steps repeatedly as you iterate towards your common goal. -It is very likely that as you do this everything will feel more and more naturally - maybe you'll even wonder why you were doing anything else before. +If your contribution is larger, you'll possibly go through (some) of these steps repeatedly as you iterate towards your common goal. +It is very likely that as you do this everything will feel more and more natural - maybe you'll even wonder why you were doing anything else before. ## Preparing to work @@ -31,7 +31,7 @@ One key difference is the turn-around time. With every first time contribution you are coming to a new (host) team. As a result, you'll need to get to know their code-base and the technology used, but also their preferred development environment (think test framework, build system). Even in cases where this type of tooling is standardized each team will have developed some individual peculiarities. -In addition to the technical side, you may be faced with differences in communication, think code-reviews. +In addition to the technical side, you may be faced with differences in communication (think code-reviews). Even if you are coming back after a while the teams' ways and members might have changed. Take your time as you would to catch up with a friend you haven't seen in a while and whom you are visiting now. @@ -70,7 +70,7 @@ The basic point is that aside of reliability in collaboration, continued presenc Do you have a large feature that you want to contribute? Excellent! Wouldn't it be horrible if all your work would be wasted? -That can happen when the host team is already building something very similar, is planning to deprecate the the software, or does not see what you are proposing to be a fit for their project? +That can happen when the host team is already building something very similar, is planning to deprecate the the software, or does not see what you are proposing to be a fit for their project. This challenge is a frequent challenge and many team relationships suffered from not agreeing in advance that a contribution is a good fit. 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_ working on the changes and submitting a pull request. @@ -122,7 +122,7 @@ If you are unsure you can always ask politely, nevertheless a guest contribution You've completed all the essential work, figured out all the quirks of the problem and the project you are contributing to, the time you've planned for the new feature to be used comes nearer and you want to make sure your contribution gets merged in as fast and smooth as possible? Here's what you can do to make reviewing and merging as easy as possible for the the trusted committer and the host team. -(This might actually be pretty similar to what you might already be doing on your own project to get your changes accepted - if that's the case: great, this is going to come natural to you!) +This might actually be pretty similar to what you might already be doing on your own project to get your changes accepted - if that's the case: great, this is going to come natural to you! ### Testing and automation @@ -152,11 +152,11 @@ To make the actual code review as easy as possible for the trusted committer or - Be civil and expect civility from the trusted committers' review. - Making pull requests too broad and large makes them more difficult to review so it will take much longer before they're accepted. - If you have a larger feature you are contributing it often helps to split it in multiple pull requests that get submitted, reviewed and accepted sequentially. +You can still bind them together with an issue that you are referring to. - Some tools also have Draft / WIP pull request functionality that you can use to explicitly mark unfinished and non-polished work and still get early feedback from your host team's trusted committers. - This allows you to ensure you are going down a path that your host team is happy to merge once it's done, adhering to the "release early, release often" idea in a way. - - The host teams' responsibility is to create an atmosphere where sharing and discussing not-totally-polished work is possible and welcome. If you can't fail safe, you can't innovate and collaborate becomes very hard. + - The host team's responsibility is to create an atmosphere where sharing and discussing not-totally-polished work is possible and welcome. If you can't fail safe, you can't innovate and collaborate becomes very hard. - Try to balance between asking for review early and providing meaningful changes to review. - - You can still bind them together with an issue that you are referring to. ## Additional articles Some of these resources might be hidden behind paywalls. From f915714c2946154b2f2e52fb45780fec6b88cd5e Mon Sep 17 00:00:00 2001 From: Johannes Tigges Date: Wed, 9 Oct 2019 10:46:24 +0200 Subject: [PATCH 12/12] Apply suggestions from code review Co-Authored-By: Isabel Drost-Fromm --- contributor/04-mechanics-of-contributing.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/contributor/04-mechanics-of-contributing.md b/contributor/04-mechanics-of-contributing.md index a4b3c00d..2f206322 100644 --- a/contributor/04-mechanics-of-contributing.md +++ b/contributor/04-mechanics-of-contributing.md @@ -61,7 +61,18 @@ Does that imply that in-person communication is forbidden? Clearly not: Where written communication shines when it comes to archiving and searchability, in-person communication shines when it comes to communication bandwidth. Try to make time to meet the people behind the names. If possible, try to meet them over your favorite beverage or some food. When you're able to hear people speak, when you know their idiosyncrasies remote collaboration will become easier. +### Building trust + +InnerSource puts huge weight on written communication - in particular when it comes to project decisions. +Does that imply that in-person communication is forbidden? +Clearly not: Where written communication shines when it comes to archiving and searchability, in-person communication shines when it comes to communication bandwidth. +Try to make time to meet the people behind the names. If possible, try to meet them over your favorite beverage or some food. +When you're able to hear people speak, when you know their idiosyncrasies remote collaboration will become easier. + +[EDITOR NOTE: There was actually a paper on how trust is build up on remote/asynchronous collaboration. Maybe I'll find that again. +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... +] [EDITOR NOTE: There was actually a paper on how trust is build up on remote/asynchronous collaboration. Maybe I'll find that again. 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... ] @@ -98,6 +109,9 @@ This is similar to the situation you and likely most people find yourself in whe Much like in Open Source projects, ask the host team if things are going nowhere even after trying to unblock yourself. The questions you ask and the answers you receive will help others coming after you solve the same issues. Make sure that your communication ends up in a searchable archive that is closely linked to the project itself. +Should you see easy improvement opportunities to reach said goal if it is not reached yet, you could try to - very politely - suggest an improvement to your host team. +Sometimes the status quo arises from pure happenstance and stays that way because no-one had a different idea or cared enough. +Suggestions for improvement might be welcome in such cases. It doesn't do either side any good for you to spin forever on a problem that could be resolved in a few-minute conversation with someone more knowledgeable about the project. It's OK to ask for help. @@ -105,6 +119,7 @@ There's one key difference though, bringing advantage to you and other people in In almost all cases you should prefer the projects' official communication channels - this can be a mailing list, a chat room, the issue tracker or something similar depending on the purpose of having a more synchronous or asynchronous way of interacting or the varying needs for structure in the communication. All of those usually have in common that they are text-based, archived, searchable and come with stable links - this means your question and the answer will be written down, references you link in those answers will also be kept reachable. This way you could benefit from this passively documented knowledge on your search and will help future contributors to have the same advantage. +Such passive documentation could even serve to enrich 'official' documentation should it happen to contain especially valuable gems such as important definitions that got created ad-hoc. As you work if you find missing (or out-of-date) documentation, do a favor to the next Contributor and update it with what you've discovered. Often projects are happy to receive additions, updates or corrections for their existing documentation as well - you've just found another opportunity to contribute! @@ -127,6 +142,8 @@ This might actually be pretty similar to what you might already be doing on your ### Testing and automation The basic point here is to enable the trusted committer to validate the contribution without your presence and to ensure easy maintainability. +Imagine you've built a feature or handling of an unsolvable quirk or important performance tweak whose code is not entirely obvious or might even look hacky / wrong at the first glance. +If you have covered this with a test - and ideally have shed some words on the rationale behind it in a comment - a future editor will get reminded about the purpose of the code and the test(s) will ensure that the value your code realizes will be kept, even in new implementations. To achieve this do the following: - Add tests for your code contribution so that validating the function of your contribution by others works well, even after some time when you work in other projects or might have stopped to contribute to this project. @@ -135,6 +152,7 @@ To achieve this do the following: - Use those to ensure that your contribution works as well as possible before opening a pull request. - Having to review defect pull requests with easy-to-fix errors often bugs trusted committers. They will not fix your code but ask you to do so. This might create more round-trips and slow the merge if there's unnecessary errors. - No one's perfect though. Try your best, use the prepared validation scripts if there are any and give it your best shot with a pull request! + - If your pull request keeps breaking tests and you can't find out why after giving it your best shot: try to highlight those tests in the pull request comment, illustrate your current understanding of the problem and ask for help on it. - Don't forget your own project that triggered your contribution in the first place. Build a modified build of the shared project with your changes and try it out in your own project that consumes it. ### Documentation and reviewability