Merge pull request #123 from MaineC/issue-tracker-usage

Add howto documentation on issue tracker usage.

Author: lenucksi

project-setup/issue-tracker.md

@@ -0,0 +1,93 @@
+# Title
+
+Issue tracker use cases
+
+# Patlet
+
+The InnerSource host team fails to make not only plans and progress but also context for changes transparent. This is solved by increasing the use cases for the project issue tracker to also serve brainstorming, implemenation discussion, and feature design.
+
+# Context
+
+The InnerSource project tooling is all setup. However the project issue tracker
+is mainly used for sharing progress. In InnerSource projects there are many more
+use cases that an issue tracker can be used for that make remote, asynchronous
+communication easier.
+
+# Problem
+
+A team develops a component that many teams in the organization depend on. It
+uses a standard issue tracker for tracking open bugs and feature requests.
+However the context in each entry is very limited. As a result potential
+contributors have no way of knowing what change exactly each issue is talking
+about.
+
+# Forces
+
+- Contributors would like to understand whether the feature that they are
+  missing is already on the roadmap. With a lot of context missing in issues
+  though it is impossible to decide whether existing issues match the
+  contributing team's needs.
+- As a result a lot of duplicate issues are being opened that the host team has
+  to deal with.
+- As context in open issues is so limited contributors are unable to help the
+  host team by implementing some of the easier issues that are open already. As
+  a result a lot of work remains in the hands of the host team.
+- With a strong focus on verbal communication it is impossible to discern after
+  a couple months or years why a certain feature was being chosen for
+  implementation. As a result refactorings, in particular simplifying the
+  component becomes an exercise in project archaeology and brain picking of people
+  who remember what was discussed.
+
+# Solution
+
+Embrace the "written over verbal" philosophy not only for pure software
+development but also during the planning phase of new features:
+
+- For bugs, planned features and feature ideas create separate issues. In each
+  of those include as much information as possible so that potential external
+  contributors are able to understand the context. Ideally, in particular for
+  easier changes, include enough information for external contributors to
+  support the host team by implementing the functionality in question.
+- Potentially use the issue tracker as a channel to ask questions. This is in
+  particular helpful if you are lacking other communication sources to tackle
+  user questions.
+- Make use of tags and categories in order to distinguish issues used for
+  different purposes.
+- For starting a brain storming session asynchronously, open an issue for
+  gathering ideas. When discussion is starting to calm down, summarize the
+  points identified in this issue in a separate document. Post that for review
+  as a pull request to drill deeper into individual points that still need
+  clarification. The resulting document can be used to publish the results in
+  other appropriate channels as well as for future reference.
+- Most issue tracker implementations allow for issue templates. Make use of
+  those not only to collect commonly needed information for bug reports but also
+  include hints about what kind of information is needed for the other usage
+  types.
+
+# Resulting Context
+
+- Making more use of the project's issue tracker for communication enables
+  external contributors to follow along and make better decisions on what to
+  contribute.
+- A focus on structured written communication enables host team members to
+  participate remotely.
+- Consistently communicating in writing means that passive documentation on
+  project decisions accumulates as a by product instead of needing added
+  attention.
+- Consistently using public communication channels leads to more humans
+  following a discussion. This means that there are more knowledgeable humans
+  that can answer questions, chime in on open issues, or point out flaws in
+  planned features that would otherwise be found only much later.
+- Moving discussions to a public discussion medium creates an opportunity for
+  potential future contributors to lurk, follow along, get comfortable and learn
+  the ways of the project long before they have the first need to get involved.
+
+
+# Known Instances
+
+* Europace AG
+
+# Status
+
+Proven
+