You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: contributor/02-becoming-a-contributor-article.asciidoc
+2-2
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,10 @@
1
1
== Becoming an InnerSource Contributor
2
2
3
-
InnerSource contributors operate outside of regular team boundaries, they are the links crossing organisational silos. As such, they need to be aware of a few common practices that make this work more effective.
3
+
InnerSource contributors operate outside of regular team boundaries, they are the links crossing organizational silos. As such, they need to be aware of a few common practices that make this work more effective.
4
4
5
5
=== Sharing Mindset
6
6
7
-
So - you're implementing a new feature for your team's product. You need some functionality to get this feature working. Instead of jumping right into the implementation, slow down for a bit: does this functionality reflect a general issue? Is it something that other teams in your organisation face as well due to the shared business domain? Is this functionality orthogonal to the domain of your project? If any of that applies, then start looking beyond your own team: is there a shared solution that you can use or improve to fit your needs? Should there be one?
7
+
So - you're implementing a new feature for your team's product. You need some functionality to get this feature working. Instead of jumping right into the implementation, slow down for a bit: does this functionality reflect a general issue? Is it something that other teams in your organization face as well due to the shared business domain? Is this functionality orthogonal to the domain of your project? If any of that applies, then start looking beyond your own team: is there a shared solution that you can use or improve to fit your needs? Should there be one?
Copy file name to clipboardExpand all lines: contributor/06-conclusion-article.asciidoc
+1-1
Original file line number
Diff line number
Diff line change
@@ -14,6 +14,6 @@ We hope you've enjoyed watching the videos, and/or and reading the articles, and
14
14
15
15
If you haven't done so already, we would like to invite you to learn more about the other aspects of InnerSource in our InnerSource learning path: http://innersourcecommons.org/learningpath/
16
16
17
-
We invite you to check out the InnerSource group http://innersourcecommons.org[InnerSource Commons] online - feel free to join the discussion and share your experiences and lessons learnt in your organization.
17
+
We invite you to check out the InnerSource group http://innersourcecommons.org[InnerSource Commons] online - feel free to join the discussion and share your experiences and lessons learned in your organization.
The Contributor section covers what it means to be an InnerSource Contributor, the aspects of behaviour that will make you a successful Contributor, contribution mechanics and the benefits of InnerSource for your team and organization.
4
+
The Contributor section covers what it means to be an InnerSource Contributor, the aspects of behavior that will make you a successful Contributor, contribution mechanics and the benefits of InnerSource for your team and organization.
Copy file name to clipboardExpand all lines: docs/adding-trusted-committers.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
This document describes how to add a new Trusted Committer to the InnerSource Learning Path.
2
2
3
-
1. Share your suggestion for new Trusted Commiter in the [:lock:learning-path-trusted-committers][learning-path-trusted-committers] private _Slack_ channel.
4
-
2. If you have some agreeement (or even [lazy consensus](https://community.apache.org/committers/lazyConsensus.html)), then move forward.
3
+
1. Share your suggestion for new Trusted Committer in the [:lock:learning-path-trusted-committers][learning-path-trusted-committers] private _Slack_ channel.
4
+
2. If you have some agreement (or even [lazy consensus](https://community.apache.org/committers/lazyConsensus.html)), then move forward.
5
5
3. Create a pull request to the [Trusted Committers] section of the README with the new person.
6
6
4. Invite the person into the [:lock:learning-path-trusted-committers][learning-path-trusted-committers]_Slack_ channel.
7
7
5. Add the person to the [@InnerSourceCommons/learning-path]_GitHub_ team.
To check both the spelling and the style of writing, we are using vale.
4
+
5
+
These checks are performed using the [isc-styles][] definitions that are maintained centrally, so that they can be applied to all projects of the InnerSource Commons.
6
+
7
+
Note that we have only started using vale recently (May 2023), and have only used it for the Patterns and the Learning Path so far. So some bumps in the road should be expected.
8
+
9
+
Further note that we are not sure yet which documentation is best to keep here versus keeping it centrally in the [isc-styles][]. So we might consolidate this documentation at a later point.
10
+
11
+
## Running the checks for the Learning Path content locally
12
+
13
+
To run the vale checks locally, you need to install:
Then synchronize your vale packages (i.e. download the [isc-styles][])
19
+
20
+
`$ vale sync`
21
+
22
+
Then run vale on the files that you want to check, e.g.:
23
+
24
+
`$ vale project-leader`
25
+
26
+
This will run the checks on all markdown and asciidoc files below the `/project-leader` folder.
27
+
28
+
Any issues found will be shown in the terminal like this:
29
+
30
+
```bash
31
+
project-leader/outline.md
32
+
3:42 error Did you really mean ISC.Spelling
33
+
'intersting'?
34
+
3:211 error Did you really mean ISC.Spelling
35
+
'organisation'?
36
+
5:154 error Did you really mean ISC.Spelling
37
+
'consollidating'?
38
+
```
39
+
40
+
## Checking new Learning Path content coming in via Pull Requests
41
+
42
+
This happens automatically, using GitHub Actions and this workflow [vale.yml](.github/workflows/vale.yml).
43
+
44
+
Output looks like this:
45
+
46
+
47
+
48
+
Note that this highlighting will only be done for any issues found in lines that were changed in the given Pull Request. The idea here is that a contributor should only have to review style issues in the content that they have added themselves.
49
+
50
+
If you (e.g. as a maintainer) want to see all potential issues that vale has found in any file that it checked, you should check the "Filtered Findings" in the **reviewdog [vale] report** that is generated automatically for any PR as well.
51
+
52
+
That report looks like this:
53
+
54
+
![Example of reviewdog \[vale\] report](https://github.com/InnerSourceCommons/InnerSourceLearningPath/assets/163029/c0a478ea-4f01-4d2b-87a4-9340761221b8)
55
+
56
+
You should only have to adapt the GitHub Actions workflow in [vale.yml](.github/workflows/vale.yml) when adding entirely new sections to the Learning Path.
57
+
58
+
## How to add exceptions to the spell checker?
59
+
60
+
There may be times where the Learning Path wants to use spelling differently from what is defined in [isc-styles][]. (Note that we hope that this will be the exception, as otherwise it won't make sense to maintain the styles centrally).
61
+
62
+
To do so, add the exceptions that you want to make to [accept.txt](.github/vale/Vocab/Base/accept.txt) or [reject.txt](.github/vale/Vocab/Base/reject.txt)
63
+
64
+
Note: We need to add a more specific description here about when to add exceptions to `Vocab/Base` in this repo, or when to rather add them to the isc-styles repo. However we have to get more hands-on experience with vale before we can write a more helpful description of this approach.
Copy file name to clipboardExpand all lines: introduction/07-faq.asciidoc
+7-7
Original file line number
Diff line number
Diff line change
@@ -16,7 +16,7 @@ It depends! An InnerSource project that encourages small pull requests and has c
16
16
=== Why not just open source?
17
17
By all means do so if the project makes sense! Some projects are specific to your company or are a competitive advantage, so you'll want to keep those as InnerSource. Some need to iterate more quickly than can be done in the open.
18
18
19
-
If your organisation isn't familiar with running open source projects, InnerSource can help people learn the skills required with a view to open sourcing in the future.
19
+
If your organization isn't familiar with running open source projects, InnerSource can help people learn the skills required with a view to open sourcing in the future.
20
20
21
21
=== Will this slow us down?
22
22
It depends on how far you're going. You'll probably be going a lot further than you think.
@@ -29,19 +29,19 @@ If so then your core team is understaffed. A healthy team is staffed so that the
29
29
You can mitigate this by setting expectation, potentially via SLAs. If contributors expect PR reviews within an hour, maybe you will be stuck reviewing PRs all the time, but if you set an SLA of 1 day or 1 week, this won't be the case.
30
30
31
31
=== How do we convince management this is a good idea?
32
-
Figure out what they want and get a https://innersourcecommons.org/stories[working example of InnerSource], preferably within your organisation, that shows them getting it. If your organization's OSPO manages InnerSource projects, reach out to them for support.
32
+
Figure out what they want and get a https://innersourcecommons.org/stories[working example of InnerSource], preferably within your organization, that shows them getting it. If your organization's OSPO manages InnerSource projects, reach out to them for support.
33
33
34
34
=== How do we convince engineers this is a good idea?
35
-
InnerSource gives engineers the opportunity to develop their career, both in terms of skills and https://patterns.innersourcecommons.org/p/praise-participants[recognition] within their organisation:
35
+
InnerSource gives engineers the opportunity to develop their career, both in terms of skills and https://patterns.innersourcecommons.org/p/praise-participants[recognition] within their organization:
36
36
37
37
* Broadens their skillset by contributing to different projects, or even different tech stacks!
38
-
* Scales the value they add to the organisation, by having their software run by more people
39
-
* Opportunity to network and collaborate with others in their organisation that they wouldn't normally
38
+
* Scales the value they add to the organization, by having their software run by more people
39
+
* Opportunity to network and collaborate with others in their organization that they wouldn't normally
40
40
41
41
Also, many engineers value open source; InnerSource embraces open source practices, and can be a step towards open source for many projects.
42
42
43
43
=== What are the expectations on part of both host and contributor?
44
-
Work together! This may be completely async via Pull Requests, or involve regular community catchups - whatever works for you.
44
+
Work together! This may be completely async via Pull Requests, or involve regular community catch-ups - whatever works for you.
45
45
46
46
Communication and support must go in both directions and be open and collaborative, fostering a culture of psychological safety. Feedback on contributions, or existing code, must be approached with a growth mindset, and as partnership to make things better.
47
47
@@ -56,4 +56,4 @@ You should also set clear contribution guidelines, and be transparent on the dir
56
56
57
57
58
58
=== How do we get people to make contributions?
59
-
Your team and wider organisation's culture must value collaboration. Focus on the business value - teams are able to unblock themselves where software they use have bugs or are missing required features. Where contributors have no immediate business need, you can https://patterns.innersourcecommons.org/p/gig-marketplace[advertise] you are looking for help.
59
+
Your team and wider organization's culture must value collaboration. Focus on the business value - teams are able to unblock themselves where software they use have bugs or are missing required features. Where contributors have no immediate business need, you can https://patterns.innersourcecommons.org/p/gig-marketplace[advertise] you are looking for help.
0 commit comments