feat: Add new process and move contributors #828

BekahHW · 2025-09-05T21:08:14Z

Description

This pull request introduces a new, automated, and conflict-free contributor management workflow for the guestbook repository. It adds contributor JSON files for multiple users, updates the contribution process and documentation, and implements several GitHub Actions to validate, welcome, and update contributors efficiently. The changes are grouped below by theme.

Automation and Workflow Enhancements:

Added .github/workflows/validate-pr.yml to automatically validate contributor PRs, ensuring only one contributor file is added per PR, the file is correctly named, and required fields are present. It also welcomes new contributors upon PR creation.
Introduced .github/workflows/validate-contributors.yml to validate contributor JSON files for structure, duplicates, and syntax on PRs and pushes.
Added .github/workflows/update-contributors.yml to automatically update the contributors section in the README using the all-contributors CLI whenever contributor files are added or changed.
Created .github/workflows/welcome-new-contributor.yml to post a congratulatory comment when a contributor PR is merged.

Contributor Onboarding and Documentation:

Updated CONTRIBUTING.md to direct users to a new step-by-step guide at docs/guides/contributor-guide.md, clarified the process for adding oneself as a contributor, and added guidance for other contribution types. [1] [2]
Overhauled .github/PULL_REQUEST_TEMPLATE.md to streamline the PR process, clearly separate new contributor submissions from other PR types, and provide explicit checklists and instructions.

Contributor Data Management:

Added a .gitkeep file to ensure the contributors directory is tracked by git and included initial contributor JSON files for several users (e.g., 02zeda.json, ATREAY.json, etc.). [1] [2] [3] [4] [5] [6] [7] [8]

Minor Improvements:

Updated the post-PR comment in intro_course_contributor.yml to streamline messaging for course contributors.

These changes collectively modernize and automate the contributor onboarding process, reduce merge conflicts, and improve the contributor experience.

What type of PR is this? (check all applicable)

rehaul the process

Related Issues

closes #827

Added to documentation?

📜 README.md
🙅 no documentation needed

Screenshot (Required for PR Review)

[optional] What GIF best describes this PR or how it makes you feel?

BekahHW · 2025-09-05T21:11:12Z

@adiati98 I still need to test this again, but I think this is working. The majority of the files changed are moving the contributors to their own json file. The docs/MiGRATION_GUIDE.md explains the changes that have been made.

I wanted to give you a chance to read through everything and ask questions.

adiati98 · 2025-09-06T06:46:20Z

@BekahHW thanks so much for this!

I'll test this locally and get back to you.

adiati98 · 2025-09-07T11:50:42Z

@BekahHW I've tested this out locally and here's my thoughts:

Missing Instructions

npm install

There's no instruction anywhere to run npm install. For folks to be able to run any npm command, they need to install it first.

Suggestion

Add an instruction to run npm install as the first step to do before creating a json file in:

"Quick Start" on root README
"Step-by-Step Instructions" on docs/guides/contributor-guide.md

Add, commit, and push changes

Once a contributor added their JSON file, there's no instruction to add, commit, and push their changes to create a PR. For new folks in OSS, they would get confuse of what to do next after adding their JSON file.

These instructions, however, are available on the terminal only if they chose to preview their profile as stated in the instruction: "5. Test locally (optional)" at docs/guides/contributor-guide.md.

Suggestions

There are a couple of options:

Add instructions to add, commit, and push changes before test locally
Make instruction no. 5 above as non optional, so folks can preview their profile before add, commit, and push, then follow the instructions from the terminal to push their changes.

I personally recommend no. 2 here.

Push changes

After running the test command — npm run contributors:test USERNAME — there will be a next steps message as below:

🚀 Next steps:
  1. Commit your file: git add contributors/USERNAME.json
  2. Create your PR: git commit -m 'Add USERNAME as a contributor'
  3. Submit and wait for merge!
  4. Check the live README in 5 minutes after merge

For folks who are new to OSS, they wouldn't know that "submit" in step 3 is to run the git push command.

Suggestions

Change the instructions to be the same with when running the preview command — npm run contributors:preview USERNAME — which has clearer steps:

🚀 Next steps:
  1. git add contributors/USERNAME.json
  2. git commit -m 'Add USERNAME as a contributor'
  3. git push origin your-branch-name
  4. Create your pull request!

Profile Details

In the "Step-by-Step Instructions" section at docs/guides/contributor-guide.md, instruction no. 2 is as follow:

2. **Add your information**
   Copy this template and fill in your details:

   ```json
   {
     "name": "Your Full Name",
     "github": "your-github-username",
     "profile": "https://your-website.com",
     "contributions": ["code", "doc", "ideas"]
   }
   ```

We have info about available contribution types in step 3. But we don't have info what to fill for the "profile": "https://your-website.com". The example here is using personal website URL. But for folks who don't have personal website, there would be questions about what to fill here.

Suggestions

Add clear info what should be filled here. This can either their personal website or URL of their GitHub profile.

Running npm Commands

The scripts are written in Python. I don't install Python on Windows. I believe some contributors also don't have Python installed on their computer.

So, for example, when I ran npm run contributors:preview adiati98, I got this error:

Python was not found error message on terminal

Suggestions

We can either:

Add an instruction to install Python 3, or
Translate the scripts to JavaScript. Note: If we want to change this to JS, we might as well consider to update the YAML files to use JS instead of Python.

Profiles on README < Contributor JSON files

Based on the below from the "Implementation Status" at docs/MIGRATION_GUIDE.md:

**README complete** with all 310 contributors displaying correctly

Before testing anything, I checked the profiles on README and compared them with the total JSON files in the contributors folder.

Here's what I found:

✅ Badge says 310
❌ There are only 121 profiles generated on README
❌ There are 310 JSON files in the contributors folder — without .gitkeep, example-contributor.json, and README.md.

The contributors' JSON files are much more than those generated on README. So, README is not complete.

My wild guess here, because the README will be generated with GH Action, there's a flaw or something missing in the update-contributors workflow: .github/workflows/update-contributors.yml.

Notes

FYI, there's a conflict that needs to be merged as I'm writing this. I've pulled it out to test.

Once it's pulled, there are merge conflicts in the README
Clicked "Accept Incoming Changes" as the conflicts are duplication. The incoming changes hold the accurate data. Both badge and total contributors are 311.
Ran npm run contributors:migrate
It added 2 new JSON files:
- A contributor that most probably got merged when you were still working on this PR
- I think I remember this one. It was a PR that's adding two different GH profiles. One of them that got pulled in this testing process was Added ManeDev.json — I've checked this one and it goes to 404. So, we can safely remove it.
Removing the 2nd one above should give us 311 total contributors. But I can't test this out until this PR is merged.

Test Command

Running npm run contributors:test USERNAME command won't give us the preview of user profile as if we run the preview command. Below is the screenshot:

Could not extract contributors section error on terminal

Validate Command

I tested this out by adding a JSON file without one of the required field. It works, as below screenshot:

However, because there are hunderds of contributors, it's quite daunting to scroll the whole list to get to the error one.

Suggestion

This is just nice to have. But it'd be great to have a print of which file is failing in the summary rather than to scroll up and try to find the error.

For example:

📊 Validation Summary:
  Files checked: 312
  Errors: 1 (adiati98.json, ❌ Missing required field: contributions)
  Warnings: 0

Add and Generate Profile Commands

Based on the docs/DEPLOYMENT_PLAN.md, we later on need to remove these from scripts in the package.json:

    "contributors:generate": "all-contributors generate",
    "contributors:add": "all-contributors add",

I had a thought about another possibility (although I'm not too fond with this 😅).

Thoughts

I'm thinking — if we want to keep everything as easy/simple as possible and only if it's possible — we can keep the ability of contributors:add command. Maybe add a new script for this instead of using the all-contributors like the current script.

Running this command would:

Prompt contributors to fill in their details.
Once it's done, it will automatically generate a new JSON file with their username as file name and store it in the contributions folder.
Unlike the current command that will automatically add and commit their changes, they still need to add, commit, and push their changes manually because these are crucial steps for contributing to any OSS project. That way, they can experience and practice this flow themselves.

The downside with this compare to manually add their profile that I can think of is probably if folks add their profile manually, then can learn to follow instructions, step by step. In my opinion adding things manually is a great learning process than to automate (almost) everything.

I might've missed something to test here, but I want to let you know what I found so far.

I've read through everything here, but I want to read one more time. Next, I will have another comment for the GH Actions workflow based on my read and understanding.

adiati98

@BekahHW, I have some questions in the comments.

Other than these, I only have one question that I can think of atm.

In the MIGRATION_GUIDE.md:

Zero merge conflicts, even with simultaneous contributions.

I just want to confirm my understanding here. So, a contributor profile will be generated on the README after we merge the PR. Is this why there won't be any merge conflicts? Even when there are multiple PRs that we merge, say, just in a minute difference?

Is there anything else that you want me to pay more attention to and give some feedback?

I'll get back to you whenever I have other things in mind.

Thank you! ✨

.github/PULL_REQUEST_TEMPLATE.md

adiati98 · 2025-09-07T15:08:13Z

.github/PULL_REQUEST_TEMPLATE.md

- [ ] 📝 Documentation Update
+## For New Contributors (Adding Yourself to Guestbook)

-## Related Issues


thoughts: I feel like creating an issue and link it to the PR is one good ways to teach contributors about the importance of opening an issue when they want to add feature or fix bugs. It's also considered as one of OSS best practices, although some repos don't require this anymore for small fixes.

suggestions: Keep creating an issue as part of contributing to guestbook repo. Therefore, keep this section here, also at the course.

adiati98 · 2025-09-07T15:13:37Z

.github/PULL_REQUEST_TEMPLATE.md

+### About Me
+**Name:** 
+**Location (optional):** 
+**What I'm learning:** 
+**Fun fact:** 


question: Do we need this section in the PR? Would it be better if we can suggest for folks to introduce themselves at GH discussion?

fix: If we want to keep this, we need some fix. The Markdown preview for this format is off because everything is inline. Let's change this to list instead.

Suggested change

### About Me

**Name:**

**Location (optional):**

**What I'm learning:**

**Fun fact:**

### About Me

- **Name:**

- **Location (optional):**

- **What I'm learning:**

- **Fun fact:**

adiati98 · 2025-09-07T15:22:52Z

.github/workflows/update-contributors.yml

+              contributions=$(python3 -c "import json; data=json.load(open('$file')); print(','.join(data.get('contributions', [])))")
+
+              # Validate required fields
+              if [ -z "$name" ] || [ -z "$github_username" ] || [ -z "$contributions" ]; then


question: Is profile (link to website) required? If so, we need to add it here for validation.

.github/workflows/validate-pr.yml

adiati98 · 2025-09-07T15:39:50Z

.github/workflows/validate-pr.yml

+              - After merge, a GitHub Action will automatically update the README
+              - You'll see your profile appear in the contributors section!
+              
+              Thanks for being part of the open source community! 🚀`;


question: Is it intentional to make this general? Or do you mean Open Source Communities?

adiati98 · 2025-09-07T15:41:48Z

.github/workflows/welcome-new-contributor.yml

+
+              **Share your success:**
+              - Post about your first open source contribution on socials
+              - Share in the [OpenSauced Discord](https://discord.gg/U2peSNf23P)


fix: This still ponting to OpenSauced Discord. We might want to point this to this repo's GH discussion.

adiati98 · 2025-09-07T16:00:00Z

docs/TESTING_GUIDE.md

+
+## For New Contributors: How to Test Your Contribution
+
+### 0. Test Locally First (Recommended!)


question: Should this start from 1?

adiati98 · 2025-09-07T18:16:35Z

docs/guides/testing-your-contribution.md

+## Next Steps from the Course
+
+After your profile appears:
+1. 🌟 **Create a highlight** of your contribution on [OpenSauced](https://app.opensauced.pizza/feed)


OpenSauced is no longer available. This step needs to be removed.

adiati98 · 2025-09-07T18:20:36Z

CONTRIBUTING.md

 - If you wish to work on an open issue, you can comment on it and tag the maintainers. Please refrain from working on an issue before it's assigned to you.

 In case you get stuck, feel free to ask for help in the [discussion](https://github.com/Virtual-Coffee/guestbook/discussions/categories/q-a).



I can't comment on the line that's not modified. But we need to fix the link in line 23 that is still ponting to VC's discussions:

In case you get stuck, feel free to ask for help in the [discussion](https://github.com/OpenSource-Communities/guestbook/discussions).

BekahHW · 2025-09-10T09:06:21Z

Yes. You should be able to merge multiple PRs quickly with no issue. It's set up like the VC Hacktoberfest issue.

Co-authored-by: Ayu Adiati <[email protected]>

Add new process and move contributors

dd82a90

adiati98 reviewed Sep 7, 2025

View reviewed changes

BekahHW and others added 5 commits September 15, 2025 13:56

Update .github/PULL_REQUEST_TEMPLATE.md

6d02b42

Co-authored-by: Ayu Adiati <[email protected]>

Update .github/workflows/validate-pr.yml

e03b565

Co-authored-by: Ayu Adiati <[email protected]>

Add node.js testing and address some comments

114bb97

Add node.js testing and address some comments

fb35348

Fix merge errors

2b2632c


		## For New Contributors: How to Test Your Contribution

		### 0. Test Locally First (Recommended!)

		- If you wish to work on an open issue, you can comment on it and tag the maintainers. Please refrain from working on an issue before it's assigned to you.

		In case you get stuck, feel free to ask for help in the [discussion](https://github.com/Virtual-Coffee/guestbook/discussions/categories/q-a).

feat: Add new process and move contributors #828

Are you sure you want to change the base?

feat: Add new process and move contributors #828

Uh oh!

Conversation

BekahHW commented Sep 5, 2025

Description

What type of PR is this? (check all applicable)

Related Issues

Added to documentation?

Screenshot (Required for PR Review)

[optional] What GIF best describes this PR or how it makes you feel?

Uh oh!

BekahHW commented Sep 5, 2025

Uh oh!

adiati98 commented Sep 6, 2025

Uh oh!

adiati98 commented Sep 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Missing Instructions

npm install

Suggestion

Add, commit, and push changes

Suggestions

Push changes

Suggestions

Profile Details

Suggestions

Running npm Commands

Suggestions

Profiles on README < Contributor JSON files

Notes

Test Command

Validate Command

Suggestion

Add and Generate Profile Commands

Thoughts

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BekahHW commented Sep 10, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

adiati98 commented Sep 7, 2025 •

edited

Loading