|
1 | 1 | # How to Contribute |
2 | 2 |
|
3 | | -1. [Take part in our Meetings and Roles](#roles-tasks-and-meetings) |
4 | | -2. [Learn our github workflow](#innersource-patterns-workflow) (Add & Review patterns) |
| 3 | +First, checkout our complete list of patterns: [Google Doc](https://docs.google.com/spreadsheets/d/17KPZdCoquTnYSj03pX4v2vn8lrSYO_6HK20u1cwaLPg/edit#gid=0) OR [public GitHub](https://github.com/paypal/InnerSourcePatterns#reviewed-patterns-proven-and-reviewed) |
5 | 4 |
|
6 | | -We encourage beginners seeking answers to jump in by creating ''donuts'' (filling in the problem, context, forces and resulting context fields but leaving the solution blank) as a way of asking the InnerSource Commons community for help (to find a proven solution or to brainstorm things to try). We encourage experts to pad their experience - these could easily become part of a book one day. Anyone can offer reviews and comments for [in-progress patterns](https://github.com/paypal/InnerSourcePatterns/pulls). |
| 5 | +We encourage beginners seeking answers to jump in by creating `donut` patterns (filling in the problem, context, forces and resulting context fields but leaving the solution blank) as a way of asking the InnerSource Commons community for help (to find a proven solution or to brainstorm things to try). |
7 | 6 |
|
8 | | -We work together via github, phone-meetings, Slack, etc. Do not hesitate to join the [#innersourcecommons](https://isc-inviter.herokuapp.com/) or #innersource-patterns slack channels and ask to be included in the patterns meetings (there is an email list). |
| 7 | +Anyone can offer reviews and comments for [in-progress patterns](https://github.com/paypal/InnerSourcePatterns/pulls). We encourage experts to pad their experience - these are hoped to become part of an Inner Source handbook one day. |
9 | 8 |
|
10 | | -[To learn about our technical github workflow, see below.](#innersource-patterns-workflow) |
| 9 | +We work together via GitHub, WebEx, Slack, etc. Do not hesitate to join the [#innersourcecommons](https://isc-inviter.herokuapp.com/) or #innersource-patterns Slack channels and ask to be included in the [patterns meetings](/meta/meetings.md) (there is an email list). |
11 | 10 |
|
12 | | -# Roles, Tasks, and Meetings |
| 11 | +Select one of the following ways to contribute, to learn our workflow: |
13 | 12 |
|
14 | | -Become involved with the people and communications of Inner Source Patterns: |
| 13 | +* A. [Write a new pattern](#a-writing-a-new-pattern) |
| 14 | +* B. [Discuss/Record early ideas](#b-discussing-early-ideas-in-issues) |
| 15 | +* C. [Review existing patterns](#c-interacting-with-patterns-reviews) |
| 16 | +* D. [Take part in our Meetings and Roles](/meta/meetings.md) <-- link to separate doc |
15 | 17 |
|
16 | | -* See our [complete list of patterns](https://docs.google.com/spreadsheets/d/17KPZdCoquTnYSj03pX4v2vn8lrSYO_6HK20u1cwaLPg/edit#gid=0) (discussed so far) |
17 | | -* See Action Items for all who are interested in patterns: |
18 | | - * Add any missing pattern or add new ones anytime |
19 | | - * Add your name if you want to be on the author team. Mark your name in blue if you want to be the coordinator. |
20 | | - * Add your name to the reviewer team if interested in the pattern |
21 | | -* Coordinator role (per pattern): Setup meetings with pattern Authors to work through the patterns. Note the team can use Google docs or any other tool to work on the pattern. However github is the final destination for the patterns. It is recommended that github be kept as up-to-date as possible. Please keep the status and target updated for each pattern in the spreadsheet. |
22 | | -* Every 2 weeks (or even sooner if necessary) we will have a meeting with a larger team and review the patterns. |
23 | | -* Folks who want to join the pattern mining team but are new to this please let us know. We can bring you up to speed. |
24 | 18 |
|
25 | | -If you don't have access yet to the google drive shared folder, contact @thyao, @silona or @cedric on the Slack channel. They can add you to the google group. @cedric or @duane can ensure you have access to the #innersource-patterns slack channel. |
26 | | - |
27 | | -Note: A transition from Wiki to Github is in the works. For the time being, some of both are being done until all is transferred. Default to github. |
| 19 | +# A. Writing a New Pattern |
28 | 20 |
|
| 21 | +The below steps can be used to create a new `donut`, `idea`, or complete pattern. The use-case here is that you have a relatively thought-out idea or problem in your head and can confidently fill out the barest of pattern fields (Solution doesn't need to be known). If you are unsure your idea is ready for this, [discuss it in an issue first](#discussing-early-ideas-in-issues). |
29 | 22 |
|
30 | | -# InnerSource Patterns Workflow |
31 | | - |
32 | | -The rest of this document describes the workflow / process for writing, reviewing and publishing |
33 | | -InnerSource ideas, donuts and patterns. It utilizes Pull Requests to facilitate |
34 | | -collaborative reviews. |
35 | | - |
36 | | -## Workflow |
| 23 | +The simplest way to create a pattern is with your browser: |
37 | 24 |
|
38 | | - |
39 | | - |
40 | | -The basic steps below can be thought of as *branch*, *commit*, *pull request*, and *review*. |
| 25 | +1. Assure you are logged into GitHub & go to the [patterns web repo](https://github.com/paypal/InnerSourcePatterns) |
| 26 | +2. Click on the 'Create new file' button |
| 27 | +3. Name the file like this example: "project-management-time-pressures.md" |
| 28 | +4. Use the [pattern template](https://raw.githubusercontent.com/paypal/InnerSourcePatterns/master/meta/pattern-template.md) to create your new [markdown](/meta/markdown-info.md) file with the description of your _idea_, _donut_, or _pattern_ |
| 29 | +5. Enter a commit message |
| 30 | + * If you are asked to 'Commit directly' vs 'Create a new branch', see [branching details](#use-branches-when-creating-new-patterns). |
| 31 | +6. Propose this new file and then also create a Pull Request (PR) |
41 | 32 |
|
42 | | -1. [Create an issue](https://github.com/paypal/InnerSourcePatterns/issues) for each new idea, donut or pattern. The issue should: |
43 | | - * contain a title of the pattern in format ex: ``pattern/badly-named-piles`` |
44 | | - * contain a short description (at least the problem) and |
45 | | - * be labeled with the appropriate label (_idea_, _donut_, _pattern_) |
46 | | -2. Create a new branch either in your browser, clone, or fork of the |
47 | | - [patterns repository][patternsRepo]. Please use the similar convention for |
48 | | - naming branches: `pattern/<pattern-name>`. Example: |
49 | | - `pattern/contracted-contributor`. |
50 | | -3. Create a _Markdown_ file with the description of the _idea_, _donut_ or |
51 | | - _pattern_ and store it in the main directory. Commit and push. |
52 | | -4. Once your contribution is ready to be reviewed, create a pull request (PR) |
53 | | - targeted at `master` and label it with _pattern_. Additionally decide whether |
54 | | - to label it with _idea_, _donut_, or _draft_ and _Ready for Review_ or _Incomplete_ |
55 | | -5. Reviewers can now use the PR features to comment on the pattern. |
56 | | -6. In case of required rework, the author should apply the labels |
57 | | - _Ready for Additional Review_ and/or _Revised_ to indicate that a 2nd review is requested. |
58 | | -7. After reviews are complete, the reviewers or author should remove the label |
59 | | - _Ready for Review_ and label the pattern _Accepted_. |
60 | | -8. Once a pattern is labeled _Accepted_ by the reviewers, one of the TCs of the |
61 | | - [patterns repository][patternsRepo] will then move the pattern to either the |
62 | | - `ideas`, `donuts` or `patterns` subdirectories, merge it to `master` and |
63 | | - close the associated issue. |
| 33 | +Your done! This creates a separate branch and creates a Pull Request (PR) all in one fell swoop! PR's are the mechanism we use for our multi-step Review process. See next steps in [Interacting with Pattern Reviews](#c-interacting-with-patterns-reviews). |
64 | 34 |
|
65 | | -When completed patterns (reviewed and accepted) are ready to be published from this InnerSourcePatterns repo to the InnerSourceCommons repo, [see our seperate PUBLISHING.md instructions](PUBLISHING.md). |
66 | | - |
67 | | - |
68 | | - |
69 | | -# Technical steps |
70 | | - |
71 | | -If you are unfamiliar with git or github, you can either: |
72 | | - * follow the technical instructions below (command line) or |
73 | | - * [use Github's GUI-based application](https://desktop.github.com/) (its rather nice and makes everything easier for a beginner). |
74 | | - |
75 | | -If you want to contribute, the workflow is done through branches. You can see the |
76 | | -available branches of this repository at [the branches URL](https://github.com/paypal/InnerSourcePatterns/branches) |
77 | | -or by clicking on the 'branches' button on the main page. |
78 | | - |
79 | | -Branches and Pull Requests (PR's) are used to bring discussion/review about a specific inner source pattern. |
80 | | -New patterns should use, as a first approach, the |
81 | | -[pattern template](meta/pattern-template.md). There are indeed multiple ways to start a discussion: |
82 | | -* Pull request your branch and the maintainers will receive a notification. |
83 | | -* Ask directly for comments to some of the maintainers. You can mention them |
84 | | -using the symbol '@' prior their nickname. |
85 | | -* Add reviewers to the Pull Request on the website - this sends requests to review your work |
| 35 | +Like the command-line better? *As an alternative, you can utilize git's native command line instead*. [We have a separate set of technical instructions here](/meta/technical-git-howto.md). |
86 | 36 |
|
87 | | -Please, when starting a new pattern, be aware that this does not exist. You can |
88 | | -have a look at some of the existing patterns in this repository. |
89 | 37 |
|
90 | | -## How can you create a branch? |
| 38 | +## Use Branches When Creating New Patterns |
| 39 | +We develop new patterns in branches with the naming convention: |
| 40 | +`pattern/<title-of-pattern-here>`. |
91 | 41 |
|
92 | | -In first place you need to create a branch (no need to ask for permission!). |
93 | | -For this, let's clone the repository: |
| 42 | +If you are asked to 'Commit directly...' vs 'Create a new branch...' |
94 | 43 |
|
95 | | -``` |
96 | | -$ git clone https://github.com/paypal/InnerSourcePatterns.git |
97 | | -``` |
| 44 | +* Assure you select **'Create a new branch...'** and name the branch like this example: "pattern/project-management-time-pressures". |
| 45 | +* This occurs when writing a new pattern via the web interface (section A above). |
| 46 | +* Only [Trusted Collaborators](/meta/trusted_collaborators.md) (TC's) are asked this; we are adding most contributors as TC's. |
98 | 47 |
|
99 | | -Then you should see some message similar to the following one: |
100 | 48 |
|
101 | | -``` |
102 | | -Cloning into 'InnerSourcePatterns'... |
103 | | -remote: Counting objects: 73, done. |
104 | | -remote: Compressing objects: 100% (37/37), done. |
105 | | -remote: Total 73 (delta 35), reused 73 (delta 35), pack-reused 0 |
106 | | -Unpacking objects: 100% (73/73), done. |
107 | | -Checking connectivity... done. |
108 | | -``` |
109 | 49 |
|
110 | | -This means that you successfully cloned the repository. Then we need to access |
111 | | -the directory and check that everything is as expected. |
112 | | - |
113 | | -``` |
114 | | -$ cd InnerSourcePatterns/ |
115 | | -$ ls |
116 | | -first-test.md README.md second-test.md third-test.md workflow.md |
117 | | -$ git branch |
118 | | -* master |
119 | | -$ git branch -a |
120 | | -* master |
121 | | - remotes/origin/HEAD -> origin/master |
122 | | - remotes/origin/master |
123 | | - remotes/origin/master-public |
124 | | - remotes/origin/pattern/badly-named-piles |
125 | | - remotes/origin/pattern/commonRequirements |
126 | | - remotes/origin/pattern/contained-innersource-enables-collaborative-product-development |
127 | | -``` |
128 | | - |
129 | | -The command 'git branch' shows you which branch you are currently working within. |
130 | | -And with 'git branch -a' you see additional branches which are local and remote (on the web). |
131 | | -There is extra information using the command '$ man git branch' in linux based systems. |
132 | | - |
133 | | -Next, in order to create a new branch as a way to start creating a new pattern, |
134 | | -you need to 'checkout' that branch. As a common nomenclature, all of the |
135 | | -pattern-related branches should start with the keyword 'pattern/'. Thus, a new |
136 | | -branch with a new pattern named as foo should be as follows: |
137 | | - |
138 | | -``` |
139 | | -$ git checkout -b pattern/foo |
140 | | -``` |
141 | | - |
142 | | -You are now in the 'pattern/foo' branch. When you create a new branch, the files |
143 | | -in the directory might appear change. Each branch can have slightly different content, |
144 | | -and that is intentional. If you need to go again to the 'master' branch or another |
145 | | -branch, you can easily 'checkout' to those as follows: |
146 | | - |
147 | | -``` |
148 | | -$ git checkout <branchname> |
149 | | -``` |
150 | | - |
151 | | -## Adding a new pattern |
152 | | - |
153 | | -Let's imagine we want to work a new pattern related to the activities of the |
154 | | -Ewoks that for some reason gave up hunting. We should choose some initial |
155 | | -name for this pattern file that could be 'ewoks-do-not-hunt.md'. |
156 | | - |
157 | | -``` |
158 | | -$ git checkout -b pattern/ewoks-do-not-hunt |
159 | | -$ touch ewoks-do-not-hunt.md |
160 | | -``` |
| 50 | +# B. Discussing Early Ideas in Issues |
161 | 51 |
|
162 | | -Once our pattern file is ready to go, we need to add the file to the repo and |
163 | | -commit that change to our new branch. |
| 52 | +If you feel that you need extra advice when dealing with patterns, please open an issue in the [ticketing system](https://github.com/paypal/InnerSourcePatterns/issues). This process is only needed when contributing early ideas that you are uncertain about. |
164 | 53 |
|
165 | | -``` |
166 | | -$ git add ewoks-do-not-hunt.md |
167 | | -$ git commit -m "Inner Source Pattern to deal with Ewoks that do not hunt" |
168 | | -``` |
169 | | - |
170 | | -And we should finally upload that branch and file to the server. |
171 | | - |
172 | | -``` |
173 | | -$ git push origin pattern/ewoks-do-not-hunt |
174 | | -``` |
175 | | - |
176 | | -Then, if you feel the pattern is ready to review, you can start a Pull Request (PR) asking |
177 | | -to join your new branch to the master branch. To do this, navigate to the github web repo |
178 | | -and get into your new branch. You should see a 'Create pull request' button while in in your branch. |
179 | | - |
180 | | - |
181 | | - |
182 | | -[commons]: http://innersourcecommons.org |
183 | | -[patternsRepo]: https://github.com/paypal/InnerSourcePatterns |
184 | | -[commonsRepo]: https://github.com/paypal/InnerSourceCommons |
| 54 | +Here are tips on starting this discussion: |
| 55 | + |
| 56 | +* [Create a new ticket](https://github.com/paypal/InnerSourcePatterns/issues/new). |
| 57 | +* Add a concise title like this example: "pattern/badly-named-piles" |
| 58 | +* Describe your problem. Think about the context of your problem and your expected output. Where do you see this problem most? What is the setup of your business and organization? Do you have opinions/ideas on what causes or leads-to the problem? |
| 59 | +* Ask any questions that you are unsure about. Are you unsure if this problem belongs here? Are you unsure on how to frame and explain the problem? |
| 60 | +* [Apply the label](https://help.github.com/articles/applying-labels-to-issues-and-pull-requests/) `Idea`. Labels can be found in the right column settings. |
| 61 | + |
| 62 | +After this process, it is our turn to drive you through the pattern creation process. We will help to land your idea and check if there are existing similar patterns. |
| 63 | + |
| 64 | + |
| 65 | + |
| 66 | +# C. Interacting with Patterns Reviews |
| 67 | + |
| 68 | +A pattern is said to be "in-review" or being "Reviewed" when we have a Pull Request with some amount of Pattern detail filled out. We then communally review, and comment-on, and OK these "in-review" patterns. There are multiple steps involved, sometimes requiring multiple re-writes, and peer-reviews. Usually though, we first look for a pattern with all the fields filled out, and then go through TWO peer-reviews. |
| 69 | + |
| 70 | +Our workflow is done through Pull Requests (PR's) and Branches. Branches are meant to separate content, so that multiple people and patterns can exist all at once. Pull Requests (PR's) are used to bring online discussion/review about a specific Inner Source pattern. |
| 71 | + |
| 72 | +FIXME Explain how to add content to in-review patterns. Explain how to add review comments and accepting a review. |
| 73 | + |
| 74 | +Below are the major steps in our Review process: |
| 75 | + |
| 76 | +1. Label your Pull Request with `pattern`. Additionally decide whether to label it with `idea`, `donut`, or `draft` and `Ready for Review` or `Incomplete` |
| 77 | +2. Reviewers can now use the PR features to comment on the pattern. |
| 78 | +3. In case of required rework, the author should apply the labels `Ready for Additional Review` and/or `Revised` to indicate that a 2nd review is requested. |
| 79 | +4. After reviews are complete, the reviewers or author should remove the label `Ready for Review` and label the pattern `Accepted`. |
| 80 | +5. Once a pattern is `Accepted` by the reviewers, one of the [Trusted Collaborators](/meta/trusted_collaborators.md) (most authors are by this point) can Merge the PR on Github. This places the .md file into the master branch / root directory. |
| 81 | + |
| 82 | +When completed patterns (reviewed and accepted) are ready to be published from this InnerSourcePatterns repo to the InnerSourcePatterns Gitbook, [see our separate PUBLISHING.md instructions](/meta/publishing.md). |
0 commit comments