Skip to content

Commit f1ee538

Browse files
committed
docs: further readme formatting
Signed-off-by: Zack Koppert <zkoppert@github.com>
1 parent 47561ac commit f1ee538

File tree

1 file changed

+19
-10
lines changed

1 file changed

+19
-10
lines changed

README.md

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -22,16 +22,17 @@ The measure-innersource tool:
2222
This tool requires an `org-data.json` file in the root of the repository that contains organizational hierarchy information. This file maps GitHub usernames to their managers, allowing the tool to determine team boundaries.
2323

2424
Example format of `org-data.json`:
25+
2526
```json
2627
{
2728
"username1": {
28-
"manager": "manager1",
29+
"manager": "manager1"
2930
},
3031
"username2": {
31-
"manager": "manager1",
32+
"manager": "manager1"
3233
},
3334
"username3": {
34-
"manager": "manager2",
35+
"manager": "manager2"
3536
}
3637
}
3738
```
@@ -50,27 +51,32 @@ Below is an example of the generated InnerSource report:
5051
### Original Commit Author: octocat (Manager: octoboss)
5152

5253
## Team Members that Own the Repo:
54+
5355
- octocat
5456
- octoboss
5557
- octodev1
5658
- octodev2
5759

5860
## All Contributors:
61+
5962
- octocat
6063
- octodev1
6164
- octodev2
6265
- contributor1
6366
- contributor2
6467

6568
## Innersource Contributors:
69+
6670
- contributor1
6771
- contributor2
6872

6973
## Innersource Contribution Counts:
74+
7075
- contributor1: 15 contributions
7176
- contributor2: 8 contributions
7277

7378
## Team Member Contribution Counts:
79+
7480
- octocat: 25 contributions
7581
- octodev1: 12 contributions
7682
- octodev2: 5 contributions
@@ -88,10 +94,10 @@ All feedback regarding our GitHub Actions, as a whole, should be communicated th
8894

8995
1. Create a repository to host this GitHub Action or select an existing repository. This is easiest with regards to permissions if it is the same repository as the one you want to measure innersource collaboration on.
9096
2. **Create an org-data.json file** in the root of your repository with your organization structure as described above.
91-
4. Copy the example below (in the next section) into your repository (from step 1) and into the proper directory for GitHub Actions: `.github/workflows/` directory with the file extension `.yml` (ie. `.github/workflows/measure-innersource.yml`)
92-
5. Update the workflow file with the appropriate configuration options as described below. The required configuration options are `REPOSITORY`, `GH_APP_ID`, `GH_APP_INSTALLATION_ID`, and `GH_APP_PRIVATE_KEY` for GitHub App Installation authentication, or `REPOSITORY` and `GH_TOKEN` for Personal Access Token (PAT) authentication. The other configuration options are optional.
93-
6. Commit the workflow file to the default branch (often `master` or `main`)
94-
7. Wait for the action to trigger based on the `schedule` entry or manually trigger the workflow as shown in the [documentation](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow).
97+
3. Copy the example below (in the next section) into your repository (from step 1) and into the proper directory for GitHub Actions: `.github/workflows/` directory with the file extension `.yml` (ie. `.github/workflows/measure-innersource.yml`)
98+
4. Update the workflow file with the appropriate configuration options as described below. The required configuration options are `REPOSITORY`, `GH_APP_ID`, `GH_APP_INSTALLATION_ID`, and `GH_APP_PRIVATE_KEY` for GitHub App Installation authentication, or `REPOSITORY` and `GH_TOKEN` for Personal Access Token (PAT) authentication. The other configuration options are optional.
99+
5. Commit the workflow file to the default branch (often `master` or `main`)
100+
6. Wait for the action to trigger based on the `schedule` entry or manually trigger the workflow as shown in the [documentation](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow).
95101

96102
### Basic Workflow Example
97103

@@ -102,16 +108,16 @@ name: Measure InnerSource Collaboration
102108

103109
on:
104110
schedule:
105-
- cron: '0 0 * * 0' # Run weekly on Sundays at midnight
106-
workflow_dispatch: # Allow manual triggers
111+
- cron: "0 0 * * 0" # Run weekly on Sundays at midnight
112+
workflow_dispatch: # Allow manual triggers
107113

108114
jobs:
109115
measure-innersource:
110116
runs-on: ubuntu-latest
111117
steps:
112118
- name: Checkout code
113119
uses: actions/checkout@v4
114-
120+
115121
- name: Measure InnerSource
116122
uses: github/measure-innersource@v1
117123
env:
@@ -161,11 +167,13 @@ The generated report includes several key metrics:
161167
### InnerSource Ratio
162168

163169
This is calculated as:
170+
164171
```markdown
165172
InnerSource Ratio = (Total InnerSource Contributions) / (Total Contributions)
166173
```
167174

168175
Where:
176+
169177
- Total InnerSource Contributions = Sum of all contributions from users outside the repository's owning team
170178
- Total Contributions = Sum of all contributions to the repository
171179

@@ -174,6 +182,7 @@ A higher ratio indicates more cross-team collaboration.
174182
### Team Ownership Determination
175183

176184
The tool determines team ownership by:
185+
177186
1. Identifying the original commit author
178187
2. Finding the original author's manager from org-data.json
179188
3. Including all users who report to the same manager in the team

0 commit comments

Comments
 (0)