Add "Solve your first starter issue" page

[U8NWXD]

This is going to be about solving something very simple. Link out from here to the tutorials for backend/frontend/etc. as other examples.

[LittleRainC]

Hi, may I work on this? Here is how I'm going to change it: I'm going to add a new page like this. Do you think this is too simple, or is this page enough?

[seanlip]

I think this is a really nice summary, thanks @LittleRainC! Just a few questions, if that's OK:

• How will you modify the wiki sidebar? Is there anything else you would do to make this page discoverable?
• In step 2, you ask folks to report a new issue ... I don't think that should be part of this process. We want to strongly encourage folks to fix an existing issue -- there is a pattern of people reporting trivial issues and then "fixing" them with a PR immediately which we want to avoid since it generally results in churn.
• Do you think people will find an issue (step 2) before setting up the repo (step 3), or should those steps be the other way around? I'm honestly not sure so would defer to your judgement, just wondering about it.
• Step 8 seems like it doesn't really come at the end of the process. Maybe instead it is better to add useful pointers on how to get help at various stages to each of the relevant steps?

Please let us know what you think about the above when you get a chance.

Thanks!

[LittleRainC]

Hi @seanlip , thanks a lot for the thoughtful feedback! Here are my thoughts on your questions:

1.Sidebar visibility:
I plan to add this page as a subpage under the “Making Your First PR” section in the wiki sidebar. While there are a few potential spots it could go, I believe this is the most fitting location since the end goal of the process is to open a PR.

2.Reporting a new issue:
That makes sense. I’ll remove the suggestion to report new issues, so we can keep the focus on solving existing ones and avoid unnecessary churn.

3.Order of steps:
I agree that finding an issue might logically come after setting up the repo. I’ll swap Step 2 and Step 3 to reflect that.

4.Getting help (Step 8):
I’ll keep the current “Get Help” page as a general support reference, but instead of relying on it as a final step, I’ll also include common problems and their solutions directly after each main step in the guide.
For example:

• After the setup section, I’ll list frequent installation issues and link to solutions.

• After the “find an issue” section, I’ll explain what to do if a good first issue is unclear or seems inactive.

• After the “write a fix plan” section, I’ll mention what to do if you're unsure about your plan or don’t get a timely response.

Hopefully, this more contextual support makes it easier for new contributors to troubleshoot as they go.

Let me know what you think — and I really appreciate your guidance! Thanks!

[LittleRainC]

According to your suggestions, here is the md file that I made on my own fork. ->Solve your first starter issue
Here are the screenshots about it:

[seanlip]

Thanks @LittleRainC! This looks great -- I've assigned you, feel free to make a PR.

Some thoughts about the contextual remediation steps:

• for point 2, we are deprioritizing the docker isntallation. Maybe better to drop the "Once your setup is successful" step or ask them to run python -m scripts.start instead?
• for point 3, they should also avoid issues marked as low-impact or backlog (see guidance here). Maybe this can replace the second bullet point since you already mentioned it above.
• for point 3, I'm not sure we want folks to leave comments asking us to determine whether an issue is right for them, as the maintainers don't have enough info to know that. Really, an issue is fine to take up if they can solve it locally. Maybe something like that could be the decision criterion?
• for point 8, I still feel that "ask for help" doesn't belong in the sequence (I don't mind keeping this info somewhere on the page, I just don't think it should be step 8). What are your thoughts on this?
• should we add points 8 and 9 for "respond to reviewers' comments" and "get your PR merged"? There are pitfalls in each of these steps as well that contributors commonly run into.

Thanks again for your work on this!

[Ash-2k3]

Hi @LittleRainC, thanks for looking into this! I had a quick question — we were also planning to link tutorials from the starting page. (You can check out the tutorials starting with the 🐾 foot icon in the sidebar — we currently have around 10–12.) Have you thought about how you might link them?

[seanlip]

Just a note, I think this is looking more like a standard wiki article than a tutorial. But I think it would be a good idea to figure out how it should be linked from the starting page as well, so that developers discover it. @LittleRainC do you have any thoughts?

[LittleRainC]

Got it. I'll look at the tutorials page and modify it!

[LittleRainC]

Hi @Ash-2k3 , thank you for the suggestions! I did go through the tutorials you mentioned, but I feel they are a bit too detailed and specific for this page. Since this guide is meant to be more general, I think it’s best to keep it concise and focused on the broader process for new contributors.

Let me know if you think there’s a way to summarize the key takeaways from those tutorials in a way that fits the scope here!

[LittleRainC]

Hi, @seanlip ! This is the latest docs after adjustment. What do you think about this? I did the following:

• Replace docker dev envrionment set up part with python dev envrionment set up
• Adjust the point 3.
• Created a "respond to reviewers' comments" as point 8 and "get your PR merged" as point 9
  This is how it looks like now. Let me know about your thoughts!
  

[seanlip]

Thanks @LittleRainC -- could you please go ahead and make a PR? Let's do further comments there, it's easier than doing it from screenshots.

A general note: for point 8 -- they should make sure they assign the reviewer (i.e. the reviewer is in "Assignees") after they've addressed the comments. This is a common mistake.

Also for the last two sections, do you want to point them to the relevant parts of the existing PR guide for more details if they need them? Not sure, just checking.

[LittleRainC]

@seanlip PR created -> #458 Thanks!!!