Adding vale for spell and style checking (InnerSourceCommons#519)

* Add vale.
* Fixes to the spelling, discovered by our new spellchecker. Mostly fixes in the Structured patterns, some for the Initial patterns as well.
* Move config for pattern syntax linting to .github
* Explain spellchecking approach in the Contributor Handbook

.github/workflows/lint-patterns.yml

@@ -1,4 +1,6 @@
 # from: https://github.com/marketplace/actions/markdown-linting-action
+# To test this locally, switch to the root of the repo and run:
+# markdownlint -r config/lint/pattern-template.js -c config/lint/pattern-template.yml patterns/2-structured/*.md patterns/2-structured/project-setup/*.md patterns/3-validated/*.md
 name: Pattern Syntax Validation
 
 on:
@@ -8,7 +10,7 @@ on:
   pull_request:
     paths:
       - ".github/workflows/lint-patterns.yml"
-      - "lint/*"
+      - ".github/lint-pattern-syntax/*"
       - "patterns/2-structured/*.md"
       - "patterns/2-structured/project-setup/*.md"
       - "patterns/3-validated/*.md"
@@ -23,6 +25,6 @@ jobs:
     - name: Lint pattern files (markdown)
       uses: avto-dev/markdown-lint@v1
       with:
-        rules: './lint/pattern-template.js'
-        config: './lint/pattern-template.yml'
+        rules: './.github/lint-pattern-syntax/pattern-template.js'
+        config: './.github/lint-pattern-syntax/pattern-template.yml'
         args: 'patterns/2-structured/*.md patterns/2-structured/project-setup/*.md patterns/3-validated/*.md'

.github/workflows/vale.yml

@@ -0,0 +1,25 @@
+name: Spelling & Styles
+
+on:
+  push:
+    branches:
+    - main
+    paths:
+    - '**.md'
+  pull_request:
+    branches:
+    - main
+
+jobs:
+  vale:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Vale Linting
+      uses: errata-ai/vale-action@reviewdog
+      with:
+        files: '["patterns/2-structured/*.md", "patterns/2-structured/project-setup/*.md"]'
+      env:
+        GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.gitignore

@@ -0,0 +1,2 @@
+# We want to ignore our vale StylesPath
+.github/vale/*

.vale.ini

@@ -0,0 +1,10 @@
+StylesPath = .github/vale
+MinAlertLevel = suggestion
+
+Packages = https://github.com/InnerSourceCommons/isc-styles/releases/latest/download/ISC.zip
+
+[*]
+BasedOnStyles = ISC
+
+; If you **don't** want to check for the correct spelling of "InnerSource", comment this in
+; ISC.InnerSource = NO

README.md

@@ -65,18 +65,18 @@ Our mission
 * [Overcoming Project Management Time Pressures](patterns/1-initial/overcoming-project-management-time-pressures.md) - *Project management believes timeline pressure and commitments on feature content does not allow for developers to spend the time needed to develop shareable code and provide support.*
 * [Introducing Metrics in InnerSource](patterns/1-initial/introducing-metrics-in-innersource.md) - *Involve all stakeholders in designing and interpreting metrics to measure the current status in terms of health and performance of the InnerSource initiative.*
 * [Shared Code Repo Different from Build Repo](patterns/1-initial/shared-code-repo-different-from-build-repo.md) - *Deal with the overhead of having shared code in a separate repository that isn't the same as the project-specific one that is tied to production builds.*
-* [InnerSource Portal - Hygiene](patterns/1-initial/innersource-portal-hygiene.md) - *Allow generation of an official badge for projects intending to be recognised as InnerSource project within your company.*
+* [InnerSource Portal - Hygiene](patterns/1-initial/innersource-portal-hygiene.md) - *Allow generation of an official badge for projects intending to be recognized as InnerSource project within your company.*
 * [Reluctance to Receive Contributions](patterns/1-initial/reluctance-to-accept-contributions.md) - *Core owner of shared asset is reluctant to take contributions due to the required maintenance that comes with them. Summary pattern that lays out four children patterns with three to be defined.*
 * [Include Product Owners](patterns/1-initial/include-product-owners.md) - *Engaging and educating Product Owners about InnerSource can help them modify their actions (e.g., in the space of KPIs) to help InnerSource collaboration work better.*
 * [Assisted Compliance](patterns/1-initial/assisted_compliance.md) - *Helping repo owners be compliant by writing their CONTRIBUTING.md for them as a pull request.*
 * [Open Source Trumps InnerSource](patterns/1-initial/open-source-trumps-innersource.md) - *Developers disregard InnerSource projects because they consider open source projects to be superior. Introducing a required evaluation of InnerSource projects before choosing an open source project increases the likelihood of the InnerSource projects to be adopted.*
 * [Transparent Governance Levels](patterns/1-initial/governance-levels.md) - *There are projects in multiple stages of InnerSource adoption. Contributors get confused when working with projects that are at different stages.*
 * [Contained InnerSource](patterns/1-initial/contained-innersource.md) - *Apply InnerSource methods to facilitate collaboration in a cross-divisional project but don't invest in soliciting contributions from outside of that project.*
 * [Good First Project](patterns/1-initial/good-first-project.md) - *An InnerSource program has been launched at an organization, and to get off to a successful start it requires some good first projects that lend themselves to InnerSource-style development. Assessing the InnerSource-readiness (fitness) of the candidate projects can help in selecting projects that have the potential to help demonstrate the power of InnerSource.*
-* [InnerSource Guidance Group](patterns/1-initial/innersource-guidance-group.md) - *A highly divergent set of development standards in different teams can slow down collaboration betweens these teams. A InnerSource Guidance Group that establishes broad governance and behavioral guidelines can help to reduce these frictions.*
+* [InnerSource Guidance Group](patterns/1-initial/innersource-guidance-group.md) - *A highly divergent set of development standards in different teams can slow down collaboration between these teams. A InnerSource Guidance Group that establishes broad governance and behavioral guidelines can help to reduce these frictions.*
 * [Unified Source Code Inventory](patterns/1-initial/source-code-inventory.md) - *In a large organization with different legal entities is often hard to get full visibility into all software assets, in particular all source code. This situation reduces the opportunities to increase business value and keep liability costs, such as software maintenance, under control across the organization as a whole. An organization-level source code inventory addresses these issues while exploiting opportunities to identify and support valuable InnerSource assets.*
-* [Explicit Shared Ownership](patterns/1-initial/explicit-shared-ownership.md) - *A software component that several teams depend on has grown to the point where owners are no longer capable of taking full ownership. There is confusion who to involve for changes. Sharing ownership explicitly and making expected behaviour visible removes ambiguity. Writing a contributions document creates a natural way to evolve ownership.*
-* [Standarized Release Process](patterns/1-initial/release-process.md) - *Teams may be reluctant to use InnerSource projects that they are unfamiliar with when there is no clear release process apparent in the repository. Providing clear release notes and a published artifact (binary, docker image, jar, etc) gives people confidence you are publishing a quality product.*
+* [Explicit Shared Ownership](patterns/1-initial/explicit-shared-ownership.md) - *A software component that several teams depend on has grown to the point where owners are no longer capable of taking full ownership. There is confusion who to involve for changes. Sharing ownership explicitly and making expected behavior visible removes ambiguity. Writing a contributions document creates a natural way to evolve ownership.*
+* [Standard Release Process and Published Artifacts](patterns/1-initial/release-process.md) - *Teams may be reluctant to use InnerSource projects that they are unfamiliar with when there is no clear release process apparent in the repository. Providing clear release notes and a published artifact (binary, docker image, jar, etc) gives people confidence you are publishing a quality product.*
 * [Overcoming the Not-Invented-Here Mindset](/patterns/1-initial/not-invented-here.md) - *Perfectly good solutions are being rejected because of "Not Invented Here" (NIH). Engineers and their managers will choose to implement functionality themselves first, even if an alternative exists. A shift towards a culture of "Proudly Found Elsewhere" can help reduce the negative impact of NIH.*
 * [Balancing Openness and Security](/patterns/1-initial/balancing-openness-and-security.md) - *While InnerSource flourishes in environments with a high degree of shared code, Security/Legal prefers the limitation of source code access to only those that need it. By making Security/Legal part of the team, introducing explicit sharing levels and security policies for shared repositories, as well as defining what qualifies as sensitive information, code sharing can be facilitated while minimizing the associated risks.*
 * [Crossing the InnerSource Chasm](/patterns/1-initial/crossing-chasm.md) - *Early InnerSource experiments have been successful. Methods that were successful convincing early teams stop working though when scaling the initiative. This chasm can be crossed by using different methods to reach people at different stages of the innovation curve.*

meta/contributor-handbook.md

@@ -47,6 +47,7 @@ To achieve a given maturity level, a pattern has to satisfy the requirements for
   - The pattern links to related patterns of this level or higher.
   - Links from the pattern to outside resources are working and are referencing a trusted resource - whether links are working is verified by [Check: Links](https://github.com/InnerSourceCommons/InnerSourcePatterns/actions/workflows/link-checker.yml)
   - The pattern is added to at least one phase of the [InnerSource Program Mind Map](../pattern-categorization/README.md).
+  - Spelling & Styles checks pass - see [Check: Spelling & Styles](https://github.com/InnerSourceCommons/InnerSourcePatterns/actions/workflows/vale.yml)
 
 - Artifacts:
   - The patterns are stored as markdown files in [/patterns/2-structured][patterns-structured].
@@ -64,7 +65,6 @@ To achieve a given maturity level, a pattern has to satisfy the requirements for
   - Uses & has no conflicts with working group terminology (defined by [Glossary](glossary.md) / implicit usage)
   - Fits & has no conflicts with existing patterns (of this maturity level)
   - Thorough review by at least two [trusted committers](../TRUSTED-COMMITTERS.md)
-  - Spell Checking passes - *Oops! We have not yet developed this*
 
 - Artifacts:
   - The patterns are stored as markdown files in [/patterns/3-validated][patterns-validated].

meta/pattern-template.md

@@ -75,7 +75,7 @@ Often, this is yourself.
 If you need to, find someone in the InnerSource Commons to be the nominal author (As Told To).
 Could also be no-one if you do not want to take on authorship (common with a donut looking for a solution).
 
-## Acknowledgements (optional)
+## Acknowledgments (optional)
 
 Include those who assisted in helping with this pattern - both for attribution and for possible future follow up.
 Though optional, most patterns should list who helped in their creation.

patterns/1-initial/crossing-chasm.md

@@ -35,7 +35,7 @@ instead of running into all of the hurdles that early adopters run into.
 - The goal is to increase collaboration, reduce duplication, increase knowledge
   sharing.
 - Some teams already adopted a lot of InnerSource best practices, often when
-  doing so they had to fix hurdles within the organisation when adopting a more
+  doing so they had to fix hurdles within the organization when adopting a more
 collaborative way of working.
 - Some associates refuse to invest time in experimenting with new ways of
   working, preferring a stable environment.

patterns/1-initial/discover-your-innersource.md

@@ -53,7 +53,7 @@ Make it easy to find the reusable code.
 * Tool with a central view (but people are more inclined to google externally than look internally)
 * Concierge service (guide) to help product people find stuff. Might not scale but could be helpful in the beginning.
 * Need some very visible lighthouse projects that start using inner source components and make positive statements about the inner source program.
-* Establish a common, asynchronous communication channel (e.g., like slack or metamorph or yammer) across team boundaries. This might not scale beyond a certain organisation size. It is possible people will start splitting this one channel into multiple channels by topic once traffic gets too high. Note: having one channel for many users of one tool might be considered an anti-pattern because they can't find it unless they already know about it.
+* Establish a common, asynchronous communication channel (e.g., like slack or metamorph or yammer) across team boundaries. This might not scale beyond a certain organization size. It is possible people will start splitting this one channel into multiple channels by topic once traffic gets too high. Note: having one channel for many users of one tool might be considered an anti-pattern because they can't find it unless they already know about it.
 * Encourage (and reward) owners of reusable code to use the same search engine to continually search for products that are candidates for use and adoption of the reusable code but not currently doing so.
 * Consider creating a marketplace for marketing InnerSource programs (management can use this mechanism to know which InnerSource projects to fund, but seeing how the marketplace reacts).
 

patterns/1-initial/explicit-shared-ownership.md

@@ -4,11 +4,11 @@ Explicit Shared Ownership
 
 # Patlet
 
-A software component that several teams depend on has grown to the point where owners are no longer capable of taking full ownership. There is confusion who to involve for changes. Sharing ownership explicitly and making expected behaviour visible removes ambiguity. Writing a contributions document creates a natural way to evolve ownership.
+A software component that several teams depend on has grown to the point where owners are no longer capable of taking full ownership. There is confusion who to involve for changes. Sharing ownership explicitly and making expected behavior visible removes ambiguity. Writing a contributions document creates a natural way to evolve ownership.
 
 # Problem
 
-An organisation is already using InnerSource best practices in several teams. The architecture of the software offered has grown organically.
+An organization is already using InnerSource best practices in several teams. The architecture of the software offered has grown organically.
 
 While talking about code ownership and accountability, teams notice that there is a component that is in a worrying state: Developed by an original team of authors it has grown it's userbase way beyond what the original team can handle. From time to time others step up to help out, however there is no formal process established. As a result, conflicts arise around who should do the work, and who should decide on project direction.
 

patterns/1-initial/governance-levels.md

@@ -32,13 +32,13 @@ There are projects on GitHub, published purely for the pleasure of the author wi
 
 There are projects where the roadmap is created in-house, hidden from public view. Where commit rights come and go with the contract of the employees of one company (e.g. MongoDB, Elastic, Tensorflow). Users are welcome to submit patches, they will even be mentored through. All development happens in the open, but control and strategy is never shared. This would be the equivalent of stage "Contributions Welcome".
 
-There are projects that share write access, but do not share the power to decide who gets write access next. This applies to everyone who is only a committer at an Apache project. There are projects that are fully shared across multiple independent organisations (e.g. k8s, any Apache project) - those would be "Shared Ownership".
+There are projects that share write access, but do not share the power to decide who gets write access next. This applies to everyone who is only a committer at an Apache project. There are projects that are fully shared across multiple independent organizations (e.g. k8s, any Apache project) - those would be "Shared Ownership".
 
-The same levels make sense inside of organisations.
+The same levels make sense inside of organizations.
 
 ## Context
 
-- InnerSource concepts are established within an organisation with multiple projects and teams adopting InnerSource.
+- InnerSource concepts are established within an organization with multiple projects and teams adopting InnerSource.
 - Internal InnerSource practices are not prescribed in detail.
 - Teams/projects have the autonomy to optimise for their local circumstances.
 
@@ -51,15 +51,15 @@ The same levels make sense inside of organisations.
 
 ## Solution
 
-The solution is to create a universally understood language to describe the InnerSource operating models that are used in your organisation.
+The solution is to create a universally understood language to describe the InnerSource operating models that are used in your organization.
 
 We define **InnerSource operating model** as a description of how much influence the core development team of a project ist willing to share with contributing teams. Or in other terms, the level of influence a contributing team can gain in the respective project.
 
 The shared language for these InnerSource operating models can be established with these steps:
 
 1. Identify the common recurring InnerSource operating models that exist in your teams and projects.
 2. Document each model in detail, and give each a distinctive name.
-3. Promote the use of these names to describe projects until the name's meaning is understood across the whole organisation.
+3. Promote the use of these names to describe projects until the name's meaning is understood across the whole organization.
 
 Examples of common InnerSource operating models (1) are:
 
@@ -77,8 +77,8 @@ Examples of promoting the model names (3) are:
 ## Resulting Context
 
 - Cross team communication occurs efficiently without confusion using terms that are universally understood and centrally documented.
-- Organisation leaders understand the nuances within practising InnerSource and make better informed and more precise decisions that are easier to communicate.
-- Increased standardisation of InnerSource practices within the organisation as the named and documented building blocks are used by teams as a menu for adoption.
+- Organization leaders understand the nuances within practising InnerSource and make better informed and more precise decisions that are easier to communicate.
+- Increased standardisation of InnerSource practices within the organization as the named and documented building blocks are used by teams as a menu for adoption.
 - Teams can adopt InnerSource best practices in a step-by-step way which makes adoption easier and less intimidating.
 
 ## Known Instances

patterns/1-initial/innersource-guidance-group.md

@@ -4,7 +4,7 @@ InnerSource Guidance Group
 
 ## Patlet
 
-A highly divergent set of development standards in different teams can slow down collaboration betweens these teams. A InnerSource Guidance Group that establishes broad governance and behavioral guidelines can help to reduce these frictions.
+A highly divergent set of development standards in different teams can slow down collaboration between these teams. A InnerSource Guidance Group that establishes broad governance and behavioral guidelines can help to reduce these frictions.
 
 ## Problem