From 56fbad7bf4b304f0a5b40ea8842cf7a20148d3d7 Mon Sep 17 00:00:00 2001 From: Himanshu Kumar Bairwa <147926718+HimanshuBairwa@users.noreply.github.com> Date: Fri, 5 Dec 2025 19:16:30 +0530 Subject: [PATCH] Revise README for clarity and structure Updated README with improved clarity and formatting. Signed-off-by: Himanshu Kumar Bairwa <147926718+HimanshuBairwa@users.noreply.github.com> --- README.md | 82 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 54 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 028fcba4..8336e614 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,82 @@

- + Good First Issue logo

+
+# Good First Issue + Welcome! 👋🏼 -**Good First Issue** is an initiative to curate easy pickings from popular projects, so developers who've never contributed to open-source can get started quickly. +**Good First Issue** is an initiative to curate “easy pickings” from popular open-source projects, so developers who have never contributed before can get started quickly. -Open-source maintainers are always looking to get more people involved, but new developers generally think it's challenging to become a contributor. We believe getting developers to fix super-easy issues removes the barrier for future contributions. This is why Good First Issue exists. +Open-source maintainers are always looking to get more people involved, but new developers often think it's challenging to become a contributor. We believe that helping developers fix super-easy issues removes the barrier for future contributions. -## Adding a new project +This is why **Good First Issue** exists. đź’ś -You're welcome to add a new project in Good First Issue, and we encourage all projects — old and new, big and small. +--- -Follow these simple steps: +## 🚀 Adding a New Project -- Our goal is to narrow down projects for new open-source contributors. To maintain the quality of projects in Good First Issue, please make sure your GitHub repository meets the following criteria: +You're welcome to add a new project to Good First Issue, and we encourage all kinds of projects — old and new, big and small. - - It has at least three issues with the `good first issue` label. This label is already present on all repositories by default. If not, you can follow the steps [here](https://help.github.com/en/github/managing-your-work-on-github/applying-labels-to-issues-and-pull-requests). +Please follow these steps: - - It has at least 10 contributors. +### 1. Check that your repository meets the criteria - - It contains a README.md with detailed setup instructions for the project, and a CONTRIBUTING.md with guidelines for new contributors. +Our goal is to narrow down projects for new open-source contributors. To maintain the quality of projects shown on Good First Issue, make sure your GitHub repository satisfies **all** of the following: - - It is actively maintained. +- âś… It has **at least three issues** with the `good first issue` label. + This label exists on all repositories by default. If you don’t see it, you can follow the steps in the [GitHub docs](https://help.github.com/en/github/managing-your-work-on-github/applying-labels-to-issues-and-pull-requests). -- Add your repository's path (in lexicographic order) in [data/repositories.toml](data/repositories.toml). +- âś… It has **at least 10 contributors**. -- Create a new pull-request. Please add the link to the issues page of the repository in the PR description. Once the pull request is merged, the changes will be live on [goodfirstissue.dev](https://goodfirstissue.dev/). +- âś… It contains: + - A `README.md` with **clear, detailed setup instructions** for the project. + - A `CONTRIBUTING.md` with **guidelines for new contributors**. -## Setting up the project locally +- âś… It is **actively maintained** (for example, there have been recent commits or issues handled in the last few months). -Good First Issue has two components — the front-end app built with Nuxt.js and a data population script written in Python. +### 2. Add your repository to the list -To contribute new features and changes to the website, you would want to run the app locally. Please follow these steps: +Once your repository meets the criteria: -1. Clone the project locally. Make sure you have Python 3 and a recent version of Node.js installed on your computer. +1. Open the file [`data/repositories.toml`](data/repositories.toml). +2. Add your repository’s path **in lexicographic (alphabetical) order**. +3. Save the file. -2. Make a copy of the sample data files for your local app to use and rename them to the filename that the app expects. **This step is important, as the front-end app won't work without these data files.** +If you’re not familiar with TOML: it’s a simple configuration file format. You can learn more at [https://toml.io](https://toml.io), but for most use cases, copying an existing entry and adjusting it will be enough. -```bash -$ cp data/generated.sample.json data/generated.json -$ cp data/tags.sample.json data/tags.json -``` +### 3. Open a Pull Request -3. Build the front-end app and start the development server. +1. Commit your changes to `data/repositories.toml`. +2. Create a new pull request to this repository. +3. In the PR description, **include a link to the issues page** of your repository (e.g. `https://github.com/owner/repo/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22`). -```bash -$ bun install # install the dependencies -$ bun dev # start the development server -``` +Once your pull request is reviewed and merged, your project will appear on [goodfirstissue.dev](https://goodfirstissue.dev/). 🎉 + +--- + +## 🛠️ Setting Up the Project Locally + +Good First Issue has two components: -The app should open in your browser. +1. A **front-end app** built with Nuxt.js. +2. A **data population script** written in Python. + +If you want to contribute new features or changes to the website, you’ll likely want to run the app locally. + +### 1. Prerequisites + +Make sure you have the following installed on your computer: + +- **Python 3** +- A recent version of **Node.js** +- **Bun**, the JavaScript runtime and package manager used by this project + +You can download Node.js from the official website, and check your version with: + +```bash +node -v