From a72ea34f9766d672475042546e9d020e21e5aa76 Mon Sep 17 00:00:00 2001 From: Shpend Kelmendi Date: Wed, 11 Mar 2026 12:20:00 +0100 Subject: [PATCH 1/8] chore: update contribution and readme with learnings --- CONTRIBUTING.md | 31 +++++++++++++++++++------------ README.md | 12 +++++++++--- 2 files changed, 28 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 409f743..8018e1e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,21 +17,28 @@ Thank you for contributing! This blog is a simple, engineer-driven space for tec ## How to contribute a blog post -1. Announce your blog post idea in the [project](https://github.com/orgs/bbvch/projects/5) with an draft item. -2. Ready to write? Assign it to yourself and set it in progress -3. Fork the repo and create a branch (e.g. `blog/my-post-slug`) for your post. -4. Add yourself as an author in `blog/authors.json` if not already present. -5. Add a dated folder under `blog/` following the pattern `YYYY-MM-DD-your-slug/`. +### First time contributing? + +1. Request to join the [@bbv-blogger team](https://github.com/orgs/bbvch/teams/bbv-blogger) if not already a member. +2. Clone the repo and setup your local environment. Follow instructions in [README.md](README.md). +3. Add yourself as an author in `blog/authors.json` if not already present. + +## Publishing workflow + +1. Announce your blog post idea in the [project (backlog column)](https://github.com/orgs/bbvch/projects/5) with an draft item. +2. Ready to write? Convert the draft item to an issue. Assign it to yourself and set it in progress in project board. +3. Create a branch (e.g. `blog/my-post-slug`) for your blog post. +4. Add a dated folder under `blog/` following the pattern `YYYY-MM-DD-your-slug/`. 1. Place the post in `index.md` (or `index.mdx`) 2. Include frontmatter (title, description, authors, tags, image) in your post 3. Put images in a local `images/` subfolder and reference them relatively (e.g., `./images/cover.png`). -6. Ready for review/publish? +5. Ready for review/publish? 1. Open a Pull Request - 2. Reference the work item you created in step 1. - 3. If you want ask somebody for a review. - 4. CI checks passed? - 5. Coordinate with maintainers to schedule the publish date (if desired) and merge when ready. As soon as it's merged, it will be live on the blog! No need to wait for a specific publish date. -7. Congrats, you published your post! Share it widely and engage with readers in the comments. + 2. Reference the work item you created in step 1 by mentioning in PR with #. + 3. If you want, ask somebody for a review. + 4. CI checks passed? Go to next step. + 5. Coordinate with @bbv-blog-admin (github team) to schedule the publish date. When approved by somebody form @bbv-blog-admin. You can merge. As soon as it's merged, it will be live on the blog! No need to wait for a specific publish date. +6. Congrats, you published your post! Share it widely and engage with readers in the comments. ### Frontmatter example @@ -41,7 +48,7 @@ title: "My Post Title" description: "Short description for the blog list card" # SEO purpose, used in BlogListPage cards authors: - autherkey # from blog/authors.yml -date: 2026-01-21 +date: 2026-01-21 # publish date, visible in blog tags: [tag1, tag2] image: ./images/cover.png --- diff --git a/README.md b/README.md index 608fd4f..ae3ef22 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,23 @@ A simple, engineer-driven technical blog (Docusaurus) for sharing posts, tutorials, sample code, and videos. -Quick start +## Requirements + +Install Node.js version 20.0 or above (which can be checked by running node -v). You can use nvm to manage multiple Node.js versions on a single machine. +When installing Node.js, it is recommended to check all checkboxes related to dependencies. +See for more details [docusaurus requirements](https://docusaurus.io/docs/installation#requirements) + +## Quick start - Install dependencies: `npm install` - Run locally: `npm start` - Build: `npm run build` -Contributing +## Contributing Please read the contribution guidelines: [CONTRIBUTING.md](CONTRIBUTING.md) -Project structure +## Project structure - `blog/` — blog posts and assets (each post in a dated folder) - `src/` — React components and theme overrides From 5e217bbfea3d2118574f2b016920d4d1a99ad9fb Mon Sep 17 00:00:00 2001 From: Shpend Kelmendi Date: Wed, 11 Mar 2026 12:55:27 +0100 Subject: [PATCH 2/8] update based on feedback --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8018e1e..4235891 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,17 +28,17 @@ Thank you for contributing! This blog is a simple, engineer-driven space for tec 1. Announce your blog post idea in the [project (backlog column)](https://github.com/orgs/bbvch/projects/5) with an draft item. 2. Ready to write? Convert the draft item to an issue. Assign it to yourself and set it in progress in project board. 3. Create a branch (e.g. `blog/my-post-slug`) for your blog post. -4. Add a dated folder under `blog/` following the pattern `YYYY-MM-DD-your-slug/`. +4. Add a dated folder under `blog/` following the pattern `YYYY-MM-DD-your-slug/`. Use the date you created your post. This date is primarily used for sorting blog posts in the directory and will be the default publish date. If the publish date differs from the date used in the folder, override the publish date with `date` in the frontmatter. 1. Place the post in `index.md` (or `index.mdx`) 2. Include frontmatter (title, description, authors, tags, image) in your post 3. Put images in a local `images/` subfolder and reference them relatively (e.g., `./images/cover.png`). -5. Ready for review/publish? +5. Ready for review/publish? 1. Open a Pull Request - 2. Reference the work item you created in step 1 by mentioning in PR with #. + 2. Reference the work item you created in step 1 by mentioning in PR with #{issue-number}. 3. If you want, ask somebody for a review. 4. CI checks passed? Go to next step. 5. Coordinate with @bbv-blog-admin (github team) to schedule the publish date. When approved by somebody form @bbv-blog-admin. You can merge. As soon as it's merged, it will be live on the blog! No need to wait for a specific publish date. -6. Congrats, you published your post! Share it widely and engage with readers in the comments. +6. Congrats, you published your post! Share it widely and engage with readers in the comments. ### Frontmatter example From 8564e8477a2e1dd6e852bb8b6da37e94cacefa51 Mon Sep 17 00:00:00 2001 From: Shpend Kelmendi Date: Wed, 11 Mar 2026 12:57:36 +0100 Subject: [PATCH 3/8] frontmatter example updated --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4235891..4d8d57a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,7 +48,7 @@ title: "My Post Title" description: "Short description for the blog list card" # SEO purpose, used in BlogListPage cards authors: - autherkey # from blog/authors.yml -date: 2026-01-21 # publish date, visible in blog +date: 2026-01-21 # publish date: use it, if you want to override the date used in the folder name tags: [tag1, tag2] image: ./images/cover.png --- From 14e4f344b3e277caf59b024e28ceea2bcb3122e4 Mon Sep 17 00:00:00 2001 From: Shpend Kelmendi <6776308+ShpendKe@users.noreply.github.com> Date: Thu, 12 Mar 2026 20:03:42 +0100 Subject: [PATCH 4/8] Update contribute file Co-authored-by: martinkoenig-bbv --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4d8d57a..79acf62 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,7 +25,7 @@ Thank you for contributing! This blog is a simple, engineer-driven space for tec ## Publishing workflow -1. Announce your blog post idea in the [project (backlog column)](https://github.com/orgs/bbvch/projects/5) with an draft item. +1. Announce your blog post idea in the [project (backlog column)](https://github.com/orgs/bbvch/projects/5) with an _draft_ item. (These cannot be seen by non-members of the [@bbv-blogger team](https://github.com/orgs/bbvch/teams/bbv-blogger) 2. Ready to write? Convert the draft item to an issue. Assign it to yourself and set it in progress in project board. 3. Create a branch (e.g. `blog/my-post-slug`) for your blog post. 4. Add a dated folder under `blog/` following the pattern `YYYY-MM-DD-your-slug/`. Use the date you created your post. This date is primarily used for sorting blog posts in the directory and will be the default publish date. If the publish date differs from the date used in the folder, override the publish date with `date` in the frontmatter. From 45d43858a6bb6543d823a88540b56b986c989a8c Mon Sep 17 00:00:00 2001 From: Shpend Kelmendi Date: Thu, 12 Mar 2026 21:16:46 +0100 Subject: [PATCH 5/8] improve contributing instructions based on board and clearer instructions --- CONTRIBUTING.md | 54 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 39 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 79acf62..134d610 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,24 +21,48 @@ Thank you for contributing! This blog is a simple, engineer-driven space for tec 1. Request to join the [@bbv-blogger team](https://github.com/orgs/bbvch/teams/bbv-blogger) if not already a member. 2. Clone the repo and setup your local environment. Follow instructions in [README.md](README.md). -3. Add yourself as an author in `blog/authors.json` if not already present. +3. [Add yourself as an author](#author-and-tag-registry) in `blog/authors.json` if not already present. +4. Join our Slack channel #tech-insights-blog ## Publishing workflow -1. Announce your blog post idea in the [project (backlog column)](https://github.com/orgs/bbvch/projects/5) with an _draft_ item. (These cannot be seen by non-members of the [@bbv-blogger team](https://github.com/orgs/bbvch/teams/bbv-blogger) -2. Ready to write? Convert the draft item to an issue. Assign it to yourself and set it in progress in project board. -3. Create a branch (e.g. `blog/my-post-slug`) for your blog post. -4. Add a dated folder under `blog/` following the pattern `YYYY-MM-DD-your-slug/`. Use the date you created your post. This date is primarily used for sorting blog posts in the directory and will be the default publish date. If the publish date differs from the date used in the folder, override the publish date with `date` in the frontmatter. - 1. Place the post in `index.md` (or `index.mdx`) - 2. Include frontmatter (title, description, authors, tags, image) in your post - 3. Put images in a local `images/` subfolder and reference them relatively (e.g., `./images/cover.png`). -5. Ready for review/publish? - 1. Open a Pull Request - 2. Reference the work item you created in step 1 by mentioning in PR with #{issue-number}. - 3. If you want, ask somebody for a review. - 4. CI checks passed? Go to next step. - 5. Coordinate with @bbv-blog-admin (github team) to schedule the publish date. When approved by somebody form @bbv-blog-admin. You can merge. As soon as it's merged, it will be live on the blog! No need to wait for a specific publish date. -6. Congrats, you published your post! Share it widely and engage with readers in the comments. +1. Idea for a blog post? + 1. Announce your idea in the backlog as a draft item. +2. Ready to write? + 1. Put your draft item in "ready to write" + 2. Share your idea with @bbv-blog-admin + 3. Find together with @bbv-blog-admin a person who would write a blog on bbv.ch + 4. Arrange a date with @bbv-blog-admin (In Roadmap view) +3. Start with writing + 1. Convert to an issue + 2. Put it "in progress" + 3. Assign it to yourself + 4. Create a branch (e.g., `blog/my-post-slug`) for your blog post. + 5. Create a [blog structure](#blog-post-structure). +4. Ready to review? + 1. Put it "in review" + 2. Create a PR and link to issue with #{issue-number} + 3. Request feedback from somebody + 4. Update based on feedback where helpful +5. Ready to publish? + 1. Request from bbv-blog-admin approval in PR + 2. When approved, you can merge +6. Congrats, you published your post! [Share it widely and engage with readers in the comments](#cross-posting). + +### Blog post structure + +``` +blog/ + YYYY-MM-DD-your-slug/ + index.mdx + images/ + cover.png + other-image.png +``` + +- Each blog post should be in its own folder under `blog/` with a name following the pattern `YYYY-MM-DD-your-slug/`. The date can be the publish date committed with @bbv-blog-admin. +- `index.mdx` is the main content file for your blog post. It should include [frontmatter](#frontmatter-example) at the top with metadata about the post (title, description, authors, date, tags, image). +- The `images/` folder is for any images you want to include in your post. The image used in the frontmatter will be the cover image for the blog list card and the blog post header. You can reference images in your content using relative paths (e.g., `./images/other-image.png`). ### Frontmatter example From fc582f204a399af9166721e0f1686da38d0da824 Mon Sep 17 00:00:00 2001 From: Shpend Kelmendi Date: Thu, 12 Mar 2026 21:20:35 +0100 Subject: [PATCH 6/8] title selection --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 134d610..3551b72 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,7 +24,7 @@ Thank you for contributing! This blog is a simple, engineer-driven space for tec 3. [Add yourself as an author](#author-and-tag-registry) in `blog/authors.json` if not already present. 4. Join our Slack channel #tech-insights-blog -## Publishing workflow +### Publishing workflow 1. Idea for a blog post? 1. Announce your idea in the backlog as a draft item. From 778f256cc22fa27be8c0b90a249211188a6a0e8f Mon Sep 17 00:00:00 2001 From: Shpend Kelmendi Date: Fri, 13 Mar 2026 09:16:41 +0100 Subject: [PATCH 7/8] add links to teams --- CONTRIBUTING.md | 37 +++++++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3551b72..5d1a8e4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,9 +30,9 @@ Thank you for contributing! This blog is a simple, engineer-driven space for tec 1. Announce your idea in the backlog as a draft item. 2. Ready to write? 1. Put your draft item in "ready to write" - 2. Share your idea with @bbv-blog-admin - 3. Find together with @bbv-blog-admin a person who would write a blog on bbv.ch - 4. Arrange a date with @bbv-blog-admin (In Roadmap view) + 2. Share your idea with [@bbv-blogger-admin team](https://github.com/orgs/bbvch/teams/bbv-blogger-admin) + 3. Find together with [@bbv-blogger-admin team](https://github.com/orgs/bbvch/teams/bbv-blogger-admin) a person who would write a blog on bbv.ch + 4. Arrange a date with [@bbv-blogger-admin team](https://github.com/orgs/bbvch/teams/bbv-blogger-admin) (In Roadmap view) 3. Start with writing 1. Convert to an issue 2. Put it "in progress" @@ -40,14 +40,16 @@ Thank you for contributing! This blog is a simple, engineer-driven space for tec 4. Create a branch (e.g., `blog/my-post-slug`) for your blog post. 5. Create a [blog structure](#blog-post-structure). 4. Ready to review? - 1. Put it "in review" - 2. Create a PR and link to issue with #{issue-number} - 3. Request feedback from somebody - 4. Update based on feedback where helpful + 1. Put it "in review" + 2. Create a PR and link to issue with #{issue-number} + 3. Request feedback from somebody + 4. Update based on feedback where helpful 5. Ready to publish? - 1. Request from bbv-blog-admin approval in PR + 1. Request from [@bbv-blogger-admin team](https://github.com/orgs/bbvch/teams/bbv-blogger-admin) approval in PR 2. When approved, you can merge -6. Congrats, you published your post! [Share it widely and engage with readers in the comments](#cross-posting). +6. Congrats, you published your post! + 1. [Share it widely](#cross-posting). + 2. Engage with readers in the comments. ### Blog post structure @@ -62,7 +64,7 @@ blog/ - Each blog post should be in its own folder under `blog/` with a name following the pattern `YYYY-MM-DD-your-slug/`. The date can be the publish date committed with @bbv-blog-admin. - `index.mdx` is the main content file for your blog post. It should include [frontmatter](#frontmatter-example) at the top with metadata about the post (title, description, authors, date, tags, image). -- The `images/` folder is for any images you want to include in your post. The image used in the frontmatter will be the cover image for the blog list card and the blog post header. You can reference images in your content using relative paths (e.g., `./images/other-image.png`). +- The `images/` folder is for any images you want to include in your post. You can reference images in your content using relative paths (e.g., `./images/other-image.png`). ### Frontmatter example @@ -74,17 +76,24 @@ authors: - autherkey # from blog/authors.yml date: 2026-01-21 # publish date: use it, if you want to override the date used in the folder name tags: [tag1, tag2] -image: ./images/cover.png +image: ./images/cover.png # relative path to the cover image for this post, used in BlogListPage cards and post page header --- ``` ### Cross-posting -- You can cross-post your content to other platforms, such as LinkedIn, Reddit, Medium, and dev.to. When cross-posting, please link back to the original post on our blog with a canonical URL to drive traffic and engagement. +- You can cross-post your content to other platforms, such as + - LinkedIn, + - Reddit, + - Medium, + - dev.to + - and other platforms. + + When cross-posting, please link back to the original post on our blog with a canonical URL to drive traffic and engagement. - You can cross-post content originally posted on your personal blog here. If you do, please add the following to your blog post (MDX file): ```html - + ``` @@ -111,6 +120,6 @@ image: ./images/cover.png - For help with the publishing workflow, CI, or tooling, contact or tag a maintainer in your PR. -## Thanks! +## Thanks Thank you for contributing. We look forward to your technical content! From 2738a8a5b34b31f786aaca056798d017cc3a68d7 Mon Sep 17 00:00:00 2001 From: Shpend Kelmendi Date: Thu, 19 Mar 2026 14:37:56 +0100 Subject: [PATCH 8/8] naming fixed --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5d1a8e4..4532eb0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,7 +38,7 @@ Thank you for contributing! This blog is a simple, engineer-driven space for tec 2. Put it "in progress" 3. Assign it to yourself 4. Create a branch (e.g., `blog/my-post-slug`) for your blog post. - 5. Create a [blog structure](#blog-post-structure). + 5. Create a [blog post folder structure](#blog-post-folder-structure). 4. Ready to review? 1. Put it "in review" 2. Create a PR and link to issue with #{issue-number} @@ -51,7 +51,7 @@ Thank you for contributing! This blog is a simple, engineer-driven space for tec 1. [Share it widely](#cross-posting). 2. Engage with readers in the comments. -### Blog post structure +### Blog post folder structure ``` blog/