Establish Automated Checks for Repo Contents about innersourcepatterns

[spier]

I tried link-checker.
It works ok. See sample output below.

If we were to start with this I think we should limit it to README.md initially, as otherwise we have way too many broken links already :)

Link checker output file: link-checker/out.md
README.md
	OK	/meta/meetings.md
	OK	30-day-warranty.md
	OK	CONTRIBUTING.md
	OK	bad-weather-for-liftoff.md
	OK	change-the-developers-mindset.md
	OK	common-requirements.md
	OK	contracted-contributor.md
	OK	crossteam-project-valuation.md
	OK	dedicated-community-leader.md
	OK	defeat-hierarchical-constraints.md
	OK	developer-incentive-alignment-for-innersource-contribution.md
	OK	gig-marketplace.md
	OK	http://bit.ly/innersource_patterns_videos
	OK	http://hillside.net/index.php/a-pattern-language-for-pattern-writing
	OK	http://innersourcecommons.org
        ...
	OK	start-as-experiment.md
	ERROR	http://creativecommons.org/licenses/by-sa/4.0/
		 (HTTP error 521)
	ERROR	i-am-not-here.md
		Stat i-am-not-here.md: no such file or directory

[spier]

I tried a markdown linter on the README.md file, just too see how that would look like.

If we don't check for line length (which the linter complaints about all over the place), we would still have these errors:

$ markdownlint README.md
README.md:1 MD041/first-line-heading/first-line-h1 First line in file should be a top level heading [Context: "This repository serves as the ..."]
README.md:3 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]
README.md:8 MD001/heading-increment/header-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h4]
README.md:59 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]
README.md:60:33 MD026/no-trailing-punctuation Trailing punctuation in heading [Punctuation: '?']
README.md:69:40 MD026/no-trailing-punctuation Trailing punctuation in heading [Punctuation: '?']
README.md:75 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]
README.md:76:20 MD026/no-trailing-punctuation Trailing punctuation in heading [Punctuation: '?']
README.md:84 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]

Would be interesting how we could arrive at a linter configuration that would be helpful, while not being a complete pain, especially for new contributors.

@maxcapraro have you worked with a markdown linter before? Any recommendations for a useful configuration?

[rrrutledge]

Spell check?

[spier]

Nice ideas. How does the output of "MD linter" look like? I have never seen one in action?

In addition a check for the require headilnes in pattern files would be nice. Basically a help for new authors to get the pattern format right. This is only really practicable once we have moved the patterns to a separate folder thought.

I think as a first step the 'dead link checker' would be most useful.
It's important that it can deal with relative links inside the markdown though (e.g. from README.md to a pattern file, as in the. case where we discovered this issue).

Two GitHub Actions that we could try:

• https://github.com/marketplace/actions/link-checker
• https://github.com/marketplace/actions/markdown-link-check

[maxcapraro]

Wow! Thanks for already looking into it :)

@maxcapraro have you worked with a markdown linter before? Any recommendations for a useful configuration?

Not really - I created the issue basically so that I don't forget to look into it :) Which - I think - I wouldn't be able to do in the next two weeks or so.

[maxcapraro]

If we were to start with this I think we should limit it to README.md initially, as otherwise we have way too many broken links already :)

Wow! We have quite many of these, indeed. So, maybe we start with the link checker instead of the linter?

[lenucksi]

That looks great, thanks for trying out some marketplace actions already, because GitHub Actions would've exactly been my next suggestion. If you, or someone else, would want to to provide a pull request with a GitHub Actions starter for the repo I'd gladly review it and merge it :D 🎉

[spier]

Anybody feels strongly about the MD linting and wants to drive it?

My take is that any MD linter configuration will find way too many issues in the MD files that we have today. Instead we could write a custom "pattern .md file linter" that checks if the pattern files contain the right headlines (from the pattern template) or similar. That might be more useful for our purposes?

My take is to leave it at the link checker that we already added, and close this issue for the time being.

[lenucksi]

Anybody feels strongly about the MD linting and wants to drive it?

My take is that any MD linter configuration will find way too many issues in the MD files that we have today.

The do indeed find quite a bit of stuff that might to be extensive for human oriented content. One can provide config to turn down the most noisy checks though.

Instead we could write a custom "pattern .md file linter" that checks if the pattern files contain the right headlines (from the pattern template) or similar. That might be more useful for our purposes?

Sounds like a good idea - And like something that could more or less work as shell script combining a bunch of grep & regexes. We'd need the rules to check for then. And provide some human readable content what is checked for (not everyone likes to read lovely monster regexes)

My take is to leave it at the link checker that we already added, and close this issue for the time being.

Would also be fine for me. What to @rrrutledge and @maxcapraro think?

[maxcapraro]

First of all: Wow! Discussion and first PR are great :)

I think (contrary to @lenucksi) that more sophisticated checks can be very very helpful. Like it does for code, automated checks allow us to focus on great semantic contents instead of syntactic issues. Though, I don't think I can commit to driving that forward within - say - the next month.

My take is to leave it at the link checker that we already added, and close this issue for the time being.

Our goal was to keep the repo (and issue tracker) as clean as possible for now - so no objection if you want to close the issue (for now ;-) )

[spier]

Ok. I vote for closing this then @maxcapraro in the spirit of clarity and focus in our repo :)

[lenucksi]

Ok. I vote for closing this then @maxcapraro in the spirit of clarity and focus in our repo :)

Closing this for the time being then. Let's come back to this issues once the time is ready.