Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

new blog linting rules #13947

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

new blog linting rules #13947

wants to merge 3 commits into from

Conversation

adamgordonbell
Copy link
Contributor

@adamgordonbell adamgordonbell commented Feb 4, 2025 •
edited
Loading

Big Goal:

  • more fine grained checks on front matter blog posts
  • including blocking publishing of posts on current date, must be scheduled into future.
  • including warning to nudge everyone in the right direction

New Rules:

  • Posts must be scheduled at least one day ahead if before noon PST, or two days ahead if after noon PST
  • Warn: if no social details
  • Warn: if scheduled for off day ( Not Tuesday-Thursday )

All old rules in place, but code in TS now and some small changes to blog posts which previous rules missed.

Example gha build:

Screenshot 2025-02-05 at 1 30 59 PM

Example local commit hook ( ie make lint) :
Screenshot 2025-02-05 at 1 32 30 PM

Example markdown file in GHA:
Screenshot 2025-02-05 at 1 34 00 PM

To accomplish that, lots of changes made:

  • Existing /lint-markdown.js moved to typescript and to using zod-matter, which makes it easier to write rules from front-matter
  • In doing so, spitting into 3 parts ( file finding, frontmatter checking and markdownlint calling)
  • Also we need a way to tell new content from existing content, so find-markdown.ts needs to know about git and GHA and gets a bit complicated.
  • Also changes to GHA git check process to make it possible to tell a new file from change file in CI

Rules:

  • Posts must be scheduled at least one day ahead if before noon PST, or two days ahead if after noon PST
  • Warn: if no social details
  • Warn: if scheduled for off day ( Not Tuesday-Thursday )

Reference:
https://docs.google.com/document/d/1zW7I4FkP0yBDnIM4gih0UvHFIrHlk57oavtpFtc7Prs/edit?tab=t.0#heading=h.sqo3w5iqc53p

@adamgordonbell
Add TypeScript linting script and update dependencies
0cee3de 
- Introduced `lint-markdown.ts` for markdown linting with TypeScript.
- Updated `lint.sh` to utilize the new TypeScript linting script.
- Added necessary TypeScript type definitions in `package.json`.
- Updated `yarn.lock` to resolve new dependencies.

Improve error messages in markdown linting script and optimize error aggregation logic.

Add new markdown linter script and update existing lint functionality

- Created `find-markdown.ts` to detect markdown files and identify new files using git or GitHub Actions.
- Refactored `lint-markdown.ts` to enhance front matter validation with structured validation results and improved error handling.
- Introduced TypeScript configuration for streamlined development.
- Added `markdownlint.d.ts` for type definitions of the markdownlint library.
- Added a detailed plan for future modernization of markdown linting processes in `plan.md`.

Add markdown linting script and runner with customizable rules

Add comprehensive list of JavaScript files and blog posts to js_files.txt

Add Zod and Zod-Matter for improved front matter parsing in Markdown files

Refactor markdown linting and validation scripts

- Replace `lint-markdown.js` and `lint-markdown.ts` with new linting logic using `validate-frontmatter.ts`.
- Update `lint.sh` to include front matter validation and utilize `yarn` for prettier checks.
- Extract front matter validation logic using `zod` for structured validation.
- Introduce improvements to script organization and error handling.

Enhance linting scripts to support different modes (git, gha) for markdown validation.

Enhance linting scripts with debug logging and improve file handling.

Refactor front matter validation functions for improved readability and performance; remove async/await where unnecessary.

Refactor front matter validation: streamline error handling, improve readability, and update interface definitions.

Update metadata and front matter validation for blog posts and events. Implemented `allow_long_title` feature and improved meta description handling.

Remove commented-out line from frontmatter validation script

Update lint script path in Makefile

Remove deprecated lint script and update lint command in the new directory.

Set DEBUG flag to 0 in lint.sh script
@pulumi-bot
Copy link
Collaborator

Your site preview for commit 33019ba is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-13947-33019ba6.s3-website.us-west-2.amazonaws.com.

@adamgordonbell
Get it all working
73861f5 
Get CI working

Update `@types/ms` resolution to version 0.7.32 in `package.json` and `yarn.lock`.

Add ts-node script and update linting commands in package.json and lint.sh.

Enhance CI workflow with debug info for PR events; add new blog post template and assets.

Refactor types in find-markdown.ts and add test PR event JSON file.

Refactor PR file handling: update to use 'files' instead of 'added_files' for added file tracking in GitHub Actions. Adjust test data accordingly.

Remove debug logging and add base branch environment variable in workflows

Enhance GitHub Actions workflow: add branch info echo and ensure make step before linting.

Refactor linting scripts and update pull request workflow

- Removed lint step from GitHub Actions workflow
- Simplified the `find-markdown.ts` script by removing GHA-related functionality
- Updated `getGitModifiedFiles` to accept a base branch parameter
- Resolved types and streamlined logic for markdown file detection
- Adjusted lint scripts to handle modes more effectively

Update markdown linting script to exclude 'node_modules' directory and add debug logging functionality in the linting process. Set DEBUG mode to off by default.

Update GitHub Actions workflow and improve file detection logic

- Upgraded `actions/checkout` from v2 to v4 and set fetch depth.
- Enhanced `getGitModifiedFiles` function to handle both local and GitHub Actions environments.
- Improved error handling and added debug logging for file detection.

Refactor GitHub Actions workflow and TypeScript script for enhanced efficiency and clarity in fetching branches and modified files.

Update GitHub warning formatter to include title and file context in the message.

Refactor blog content in "copilot-lessons" to emphasize the balance between prompt engineering and traditional software engineering.

Update blog title, enhance linting script for error reporting, and refactor frontmatter validation formatters.

Add new blog post template and update validation for front matter date field.

Refactor blog post front matter: Removed unnecessary comments, updated meta description, added front matter validation documentation.

Update blog post date and enhance front matter validation rules in the linting script.

Add date validation functions to ensure publish dates comply with PST rules

- Implemented `getNowInPST` for current PST date and time.
- Added `toDateOnly` to strip time from date objects.
- Created `getEarliestAllowedDate` to determine earliest publishable date based on noon cutoff.
- Introduced `validatePublishDate` to validate front matter dates against rules.
- Updated front matter validation checks to incorporate new date validation logic.

Refactor date validation logic to ensure publish dates are in PST and issue warnings for suboptimal publish days and time components. Update blog post date.

Add validation for social sharing fields in new posts. Warn if `twitter` or `linkedin` are missing.

Refactor frontmatter validation comments for clarity and consistency. Remove temporary file validation condition.

Refactor blog post creation and update date format

- Replace inline `hugo new` command with a dedicated script (`new-blog-post.sh`) to streamline blog post creation.
- Update blog post archetype to use current date format in ISO 8601.
- Remove unused linting documentation and related test JSON files.
@pulumi-bot
Copy link
Collaborator

Your site preview for commit 4c39ace is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-13947-4c39ace4.s3-website.us-west-2.amazonaws.com.

adamgordonbell
adamgordonbell commented Feb 5, 2025
View reviewed changes
scripts/lint/markdownlint-runner.ts
@@ -0,0 +1,199 @@
import * as path from 'path';
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adapted from previous lint-markdown.js

@adamgordonbell adamgordonbell marked this pull request as ready for review February 5, 2025 19:04
@adamgordonbell adamgordonbell changed the title Draft: blog linting rules new blog linting rules Feb 5, 2025
adamgordonbell
adamgordonbell commented Feb 5, 2025
View reviewed changes
scripts/lint/find-markdown.ts
@@ -0,0 +1,212 @@
import * as fs from 'fs';
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adapted from previous lint-markdown.js but expanded to cover if file is net new when compared to parent branch.

adamgordonbell
adamgordonbell commented Feb 5, 2025
View reviewed changes
scripts/new-blog-post.sh
@@ -0,0 +1,13 @@
#!/bin/bash
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Posts now default to future Wednesday, to encourage scheduling

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@sean1588 sean1588 Awaiting requested review from sean1588

@thoward thoward Awaiting requested review from thoward

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@adamgordonbell @pulumi-bot