[DOC] README: Revise for new Consulting blog flow & general edits #704

bskinn · 2023-03-28T16:25:00Z

With the merge of #577, the Consulting blog is now operating on analogous GitHub-/Markdown-based machinery to the Labs blog.

The primary goal of this PR is to update the README to reflect this new Consulting blog workflow.

I also took the liberty of making some additional general edits to the README.

Closes #702.

vercel · 2023-03-28T16:25:07Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
consulting	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 27, 2023 5:51pm
labs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 27, 2023 5:51pm

bskinn · 2023-03-28T17:28:51Z

Would appreciate your review on these changes when you have a chance, @gabalafou -- thanks!

gabalafou

My inner librarian heart is warmed by these README updates, thank you!

I don't think any of my suggestions are blocking, but you might want to incorporate some of them, and we have to fix the merge conflict (banner vs overlay) before we can merge this.

gabalafou · 2023-06-15T12:38:19Z

README.md

    `./apps/consulting/posts`, respectively.
+- **Static content** for each site lives under `./apps/labs/public` and
+  `./apps/consulting/public`, respectively.
+  - The `public` path element is removed when the site is built: for example, a


Thanks for adding this! It's a common convention but it has caused confusion in the past.

I've seen it ~50/50 with /static being the magic folder name for static content. It took me a decent while with the codebase to realize it was doing the same thing.

gabalafou · 2023-06-15T12:44:15Z

README.md

@@ -174,7 +176,7 @@ These are the concrete steps to follow to move your code from branch to branch:
   `develop` branch.
   - Consider doing a
     [squash-merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-pull-request-commits),
-     especially if your pull request is relatively small, to keep a
+     except if your pull request is relatively small, to keep a


I don't think I made my point here clearly.

If you have a one-line code change but several commits that are like:

sha1 fix code bug
sha2 typo
sha3 another typo
sha4 hopefully last typo

I would strongly prefer you to squash those commits.

But you have a PR that contains 100s of lines of code changes, which are chunked into commits, then maybe don't squash those commits.

Good point -- so, I'd think we'd want to squash all merges to develop, then.

My reasoning for squashing aggressively is because we're working on GitHub, where the original chain of commits is retained in the closed PR, even when what gets merged to the base branch is a single squash.

It has the benefit of clean base branch history, while still retaining the full arc of the work process in the PR.

So, I'm inclined to strengthen this to something like "Please use GitHub's squash-merge functionality for all PRs to develop."

For merges to main, since release/hotfix branches can have weird history topology (e.g., a release gets hotfixed, then merges to main, then merges to develop) that would be hard to follow if it got squash-merged to either main or develop, I'm inclined to do simple commit merges there.

I'll write out my case in a new commit here, see what you think on your next review pass.

+1 to all of that

gabalafou · 2023-06-15T12:46:28Z

README.md

-should be a banner that explains that you are looking at a preview of the site.
-This helps reduce confusion when screenshots are shared. This banner should not
-be present on a production build of the site.
+should be a gray or yellow banner that indicates that you are looking at a


I thought we already changed the "banner" to "overlay"?

Do you branch off an older version of develop?

This PR was opened well before that change in language. I'll need to rebase/merge from develop & deal with any conflicts before this is ready to merge.

develop merged in, conflicts fixed, and straggling instances of "banner" converted to "overlay" in this branch.

Should be taken care of on next commit.

gabalafou · 2023-06-15T12:46:58Z

README.md


 The preview/development environment banner should allow the user to toggle
 between seeing published versus draft/saved Storyblok content. The banner should
 change colors to indicate which of the two content preview modes the user is in
-(that is, whether they are seeing draft or published content from Storyblok).
+(that is, whether they are seeing draft (yellow banner) or published (gray


change open parens to dash so we don't have parentheses inside parentheses

Suggested change

(that is, whether they are seeing draft (yellow banner) or published (gray

—that is, whether they are seeing draft (yellow banner) or published (gray

Changed, will show in next commit.

gabalafou · 2023-06-15T12:47:51Z

README.md


 The preview/development environment banner should allow the user to toggle
 between seeing published versus draft/saved Storyblok content. The banner should
 change colors to indicate which of the two content preview modes the user is in
-(that is, whether they are seeing draft or published content from Storyblok).
+(that is, whether they are seeing draft (yellow banner) or published (gray
+banner) content from Storyblok).


Suggested change

banner) content from Storyblok).

banner) content from Storyblok.

gabalafou · 2023-06-15T13:26:17Z

README.md

+   `<site>-blog/new-hello-world-post`.
+2. Add post images (feature, hero, and any for the post body) to
+   `apps/<site>/public/posts/<post-name>`.
+3. Add a new `.md|.mdx` file inside the `app/<site>/posts` directory. Make sure


Suggested change

3. Add a new `.md|.mdx` file inside the `app/<site>/posts` directory. Make sure

3. Add a new `.mdx` file inside the `app/<site>/posts` directory. Make sure

As I mentioned in my other note, we should forget .md. It's especially misleading because in normal Markdown you can create code blocks but "indented code does not work in MDX."

I think all of the posts for both blogs are .md files. Should we rename them? Not great to have the churn in the file history.

If nothing else, any blogs not yet on develop should be renamed to .mdx?

If it would be good to rename the .md blog source files to .mdx, a good time to do that might be as part of #746, since we're touching all those files to add the categories [] anyways?

I made this change locally, will reflect on next push

gabalafou · 2023-06-15T13:28:30Z

README.md

+   format of the conventional commit. See the
+   [Conventional Commits docs](https://www.conventionalcommits.org/en/v1.0.0/).


Suggested change

format of the conventional commit. See the

[Conventional Commits docs](https://www.conventionalcommits.org/en/v1.0.0/).

[Conventional Commit format](https://www.conventionalcommits.org/en/v1.0.0/).

I didn't actually know about this until today 😅

Made this change in both places it appears. Also capitalized 'Conventional Commit' in the flow of text, both places.

gabalafou · 2023-06-15T13:29:32Z

README.md

+   `consulting 🤝` labels to the PR.
+6. Wait for someone on the website team to review the new blog post. If
+   everything is ok, the PR will be merged to the `develop` branch. The blog
+   post will then go live with the next site build (merge to `main`).


Suggested change

post will then go live with the next site build (merge to `main`).

post will then go live with the next production deployment (merge to `main`).

Since "production deployment" is the language that Vercel uses

I made this change, and several others for build -> deployment.

There is an important semantic difference here, because e.g. if I run npm run build locally, then it is building the site, but not deploying it. Please check to make sure that I've not messed these semantics up with my changes.

gabalafou · 2023-06-15T13:31:21Z

README.md

+   format of the conventional commit.
+   See the
+   [Conventional Commits docs](https://www.conventionalcommits.org/en/v1.0.0/).


Suggested change

format of the conventional commit.

See the

[Conventional Commits docs](https://www.conventionalcommits.org/en/v1.0.0/).

[Conventional Commits format](https://www.conventionalcommits.org/en/v1.0.0/).

gabalafou · 2023-06-15T13:34:28Z

README.md

+   `consulting 🤝` labels to the PR.
+6. Wait for someone on the website team to review the new blog post. If
+   everything is ok, the PR will be merged to the `develop` branch. The blog
+   post will then go live with the next site build (merge to `main`).

 ### Adding a new blog category

 1. Create a new feature branch.


I realize that you didn't create this section but it feels a little odd to me that we have it at all. Because I'm guessing that a new blog category will be added with a blog post that wants a new category. And in that case it would make sense to me to push the new category and blog post together.

In fact, I would prefer NOT to have a developer follow this section to add a new blog category (without a corresponding blog post) because then the category will show up on the website without any blog posts under it.

I'm solidly +1 to this, new categories only being created when posts are created that need them. I'll rewrite a draft for you to review.

Related, see #713.

Co-authored-by: gabalafou <[email protected]>

bskinn · 2023-06-27T17:36:22Z

@gabalafou Ok, I've made edits per your requests. Ready for your next pass.

Once you're satisfied with the content, I want to make a final text reflow pass over README.md, if that's all right with you.

bskinn · 2023-06-27T17:48:12Z

@gabalafou Annoying. The changes to the three blogs are due to automatic linting of staged files that husky does when I commit. I can't revert those files without figuring out how to temporarily disable that linting.

Nice, --no-verify does work to skip Husky linting, good to know. 👍

bskinn · 2023-06-28T13:43:47Z

Hm. With the migration to Wordpress complete, we should probably make note here of the consulting Jamstack site being idle, and that all Consulting site matters route through Marketing/Design...

bskinn · 2024-05-08T15:34:16Z

👋 @gabalafou @pavithraes Closing to ~relinquish my ownership of the contribution, and because the changes are relatively stale since they originated before the Consulting site migration to WordPress.

Revise README for blog flow & add some screenshots

be78f06

bskinn added area: documentation 📖 Improvements or additions to documentation labs 🔭 Items related to the Labs website consulting 🤝 type: maintenance 🛠 area: contributor experience 👩🏼‍🎤 labels Mar 28, 2023

bskinn requested a review from gabalafou as a code owner March 28, 2023 16:25

bskinn added 3 commits March 28, 2023 12:25

Complete incomplete sentence

c4a9c21

First pass at fixing TOC entries

8016119

Add further note about different categories.jsons

f8a8773

vercel bot deployed to Preview – consulting March 28, 2023 16:35 View deployment

vercel bot deployed to Preview – labs March 28, 2023 16:38 View deployment

Collect MDX mentions and links together

1f53625

vercel bot deployed to Preview – consulting March 28, 2023 17:19 View deployment

vercel bot deployed to Preview – labs March 28, 2023 17:23 View deployment

Add instructions about common hero for Consulting

fce92b0

vercel bot deployed to Preview – labs March 30, 2023 02:46 View deployment

vercel bot deployed to Preview – consulting March 30, 2023 02:47 View deployment

Specify to create blog branches off develop

bf66af8

vercel bot deployed to Preview – labs March 31, 2023 04:29 View deployment

vercel bot deployed to Preview – consulting March 31, 2023 04:30 View deployment

Fix conventional commits link text

ec65cf5

bskinn force-pushed the cons-blog-instructions branch from a1ba746 to ec65cf5 Compare April 3, 2023 14:41

vercel bot deployed to Preview – consulting April 3, 2023 14:46 View deployment

vercel bot deployed to Preview – labs April 3, 2023 14:49 View deployment

pavithraes self-requested a review May 28, 2023 10:09

Add remaining additions/fixes

1ce65ce

vercel bot deployed to Preview – labs June 14, 2023 18:42 View deployment

vercel bot deployed to Preview – consulting June 14, 2023 18:44 View deployment

gabalafou requested changes Jun 15, 2023

View reviewed changes

Merge branch 'develop' into cons-blog-instructions

aeea5ac

bskinn requested review from trallard and rgommers as code owners June 27, 2023 15:36

vercel bot deployed to Preview – labs June 27, 2023 15:39 View deployment

vercel bot deployed to Preview – consulting June 27, 2023 15:41 View deployment

Reformat categories.json description section

31616ab

Co-authored-by: gabalafou <[email protected]>

vercel bot deployed to Preview – consulting June 27, 2023 17:26 View deployment

vercel bot deployed to Preview – labs June 27, 2023 17:29 View deployment

Edit README per code review

93facc0

vercel bot deployed to Preview – labs June 27, 2023 17:39 View deployment

vercel bot deployed to Preview – consulting June 27, 2023 17:40 View deployment

Revert auto-linting changes to blog files

a5e7aa3

vercel bot deployed to Preview – labs June 27, 2023 17:50 View deployment

vercel bot deployed to Preview – consulting June 27, 2023 17:51 View deployment

bskinn closed this May 8, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOC] README: Revise for new Consulting blog flow & general edits #704

[DOC] README: Revise for new Consulting blog flow & general edits #704

bskinn commented Mar 28, 2023 •

edited

Loading

vercel bot commented Mar 28, 2023 •

edited

Loading

bskinn commented Mar 28, 2023

gabalafou left a comment

gabalafou Jun 15, 2023

bskinn Jun 27, 2023

gabalafou Jun 15, 2023

bskinn Jun 15, 2023

bskinn Jun 27, 2023

gabalafou Jun 27, 2023

gabalafou Jun 15, 2023

bskinn Jun 15, 2023

bskinn Jun 27, 2023

gabalafou Jun 15, 2023

bskinn Jun 27, 2023

gabalafou Jun 15, 2023

bskinn Jun 27, 2023

gabalafou Jun 15, 2023

bskinn Jun 15, 2023

bskinn Jun 27, 2023

bskinn Jun 27, 2023

gabalafou Jun 15, 2023

bskinn Jun 27, 2023

gabalafou Jun 15, 2023

bskinn Jun 27, 2023

gabalafou Jun 15, 2023

gabalafou Jun 15, 2023

bskinn Jun 15, 2023

bskinn commented Jun 27, 2023

bskinn commented Jun 27, 2023

bskinn commented Jun 28, 2023

bskinn commented May 8, 2024

	(that is, whether they are seeing draft (yellow banner) or published (gray
	—that is, whether they are seeing draft (yellow banner) or published (gray

	banner) content from Storyblok).
	banner) content from Storyblok.

	3. Add a new `.md\|.mdx` file inside the `app/<site>/posts` directory. Make sure
	3. Add a new `.mdx` file inside the `app/<site>/posts` directory. Make sure

		format of the conventional commit. See the
		[Conventional Commits docs](https://www.conventionalcommits.org/en/v1.0.0/).

	format of the conventional commit. See the
	[Conventional Commits docs](https://www.conventionalcommits.org/en/v1.0.0/).
	[Conventional Commit format](https://www.conventionalcommits.org/en/v1.0.0/).

	post will then go live with the next site build (merge to `main`).
	post will then go live with the next production deployment (merge to `main`).

[DOC] README: Revise for new Consulting blog flow & general edits #704

[DOC] README: Revise for new Consulting blog flow & general edits #704

Conversation

bskinn commented Mar 28, 2023 • edited Loading

vercel bot commented Mar 28, 2023 • edited Loading

bskinn commented Mar 28, 2023

gabalafou left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bskinn commented Jun 27, 2023

bskinn commented Jun 27, 2023

bskinn commented Jun 28, 2023

bskinn commented May 8, 2024

bskinn commented Mar 28, 2023 •

edited

Loading

vercel bot commented Mar 28, 2023 •

edited

Loading