July Task: GH Actions w/ Markdownlint

[lijenn]

Prototype the GH action extension, Stylelint with Reviewdog (https://github.com/marketplace/actions/run-stylelint-with-reviewdog)

Possible suggestions extensions to look into:

• https://github.com/remarkjs/remark and https://github.com/remarkjs/remark-lint
• https://github.com/marketplace/actions/remark-action --> I had trouble implementing these, was successful with Markdownlint for GH Actions (edit:5/14)

to fork on the TeamPSD repo (https://github.com/lijenn/teampsd_prototype) while thinking of the team's different personas.

1) Hypothesis: I/HQ needs a linter to indentify markdown standards that can be integrated within GH Actions. This should help speed up the automation process to reduce the need of a "multistretch manager" or "busy PI" and scale within our platform. 2) CTA Youtube Prototype: Insert link 3) CTA Retrospective Written: See below 4) Feedback: Comment below with feedback for team for any pain points they are experiencing and possible solutions or hints towards the right direction for pain points you see in my video and written prototype.

Bold important key terms that could provide next steps in directions.

---

Retrospective CTA: Week 2 Day 1:

• Trying to implement the GH Action extension itself.
• How does the yml file works (understanding the syntax of the file).
• How to incorporate the piece of the extension in the syntax.
• Seems like the extension is working, but documentation mentions that the Stylelint rules...

  Rules determine what the linter looks for and complains about. There are over 170 rules built into stylelint.

No rules are turned on by default and there are no default values. You must explicitly configure each rule to turn it on.

• Implement the build runs with the extension in the syntax (will need to figure out requirements to add on this, can it do what it says to do, can it actually address my/my team's pain point).
• Marketplace listing shows an example usage, mentions to download Stylelint
• Stylelint user guide documentation --> Will Git be need to used? User guide documentation seems to be talking in the context of Git..

Takeaway: Understanding and reading the existing documentation is hard :( But do-able!

Day 2:

• Figuring out what to install through Git? Command line? (Order of Operations: Xcode > Homebrew > node.js (node.js download automatically downloads npm) > use npm to install Stylelint)
• How do I add requirements/"plugins" to my yml with the existing rules of the extension
• Doesn't seem like it will address markdown...Stylelint may be the wrong lint to even look at right now! (Check out Remark & Remark-lint??)
• Look into other linters and their pre-existing rules. Plugins require us to create new rules, seems like this may need to be in Javascript
• Look into Remark & Remark-lint
• Still need to explore Git to see if this is a "root" language needed for this. Seems like it is based on the existing documentation that I am reading.

Takeaway: Should have looked into the rules of Styelint through the documentation instead of just looking at the marketplace listing. Again, look at the existing documentation.

Day 3:

• Looking into Remark & Remark-lint.
• Had issues learning how to implement this with Actions on GitHub.
• Complied resources regarding using another linter, markdownlint, that could be used integrated with Actions.

Day 4

• Looking into how to implement markdownlint with Actions on GH.
• Needs context and understanding of how to use some Git Commands.
• May need a text editor, VS Code?
• Will test out this implementation to see if it can work on GitHub.
• Recording prototype video (may need to cut some stuff or redo some stuff, was learning while going thru everything, may be a really long video).
• Also needs to write up in depth guide on what I did and how I did it for other personas.
• Questions:
  • Could folks to learn basic Git/Bash commands (some Git commands were used from the intro video on DataCamp)?
  • Could we use VS Code to edit markdown files...seems like there are style guides that we could set up and this would automatically detect the discrepancies as you're writing/creating the .md file...would eliminate the need of CI on Actions (at least for detecting .md style formatting) https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint?
  • Although, current CI can detect any discrepancies within ALL .md files, feature not a bug.
  • Also would need to learn how to send a pull request to GH from VS code if we choose to edit .md files on VS Code

Day 5

• Need to look back at my learning resources and prepare prototype video and guide for next personas to test: Thinking of @anthonycpichardo or @staceypark

• Think of guide and other user personas, think about how, why, when, where, like @lziim guide

• Order or Operations for key platforms needed:

  1. GH Actions > yaml file in Actions > package.json > .markdownlint.yml file to pass through config file
  2. Terminal > Basic Git & Bash commands (refer to DataCamp for intro & make a list of the commands I used) > run markdownlint locally
  3. VS Code
  4. Action/CI output

Need to determine: Could I just setup 2-3 and everyone else just needs step 1? If yes: Will need to go in depth into about the standard rules for the .markdownlint.yml If no: Go through 1-4.

Week 3 Day 1:

• Confirmed, Anthony was able to transfer my GH Actions workflow to his forked TeamPSD without the need to set up the linter locally.
• Next steps:
  • I need to write up documentation following Hester's vingette (https://github.com/jimhester/lintr/blob/master/vignettes/creating_linters.Rmd).
  • Video prototype me going through the configuration files to teach others how to read through Markdownlint rules (https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md) and where to add them in the .markdownlint.yml file.

[lijenn]

removed my user journey here to be posted in the top comment.

[lzim]

love how you added a blocker for #1192 @lijenn ! ❤️

[lijenn]

Moved to #1450 for SIM UI & Dev team to help with CI Workflow.