Skip to content
This repository has been archived by the owner on Apr 29, 2024. It is now read-only.

Commit

Permalink
Apply suggestions from code review
Browse files Browse the repository at this point in the history 
Co-authored-by: Ayu Adiati <[email protected]>
  • Loading branch information
@jdwilkin4 @adiati98
jdwilkin4 and adiati98 authored Dec 14, 2023
1 parent ee8d2ed commit 46665e6
Showing 1 changed file with 30 additions and 30 deletions.
60 changes: 30 additions & 30 deletions how-to-setup-your-project.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ There are a lot of things to consider when setting up your open source project.

## How to Write a Good README

A `README.md` is an introduction into what your open source project is all about. A good `README.md` should be clear, concise, up to date, and detailed. This file is located in your root directory and serves as the first impression for your contributors.
A `README.md` is an introduction to what your open source project is all about. A good `README.md` should be clear, concise, up-to-date, and detailed. This file is located in your root directory and serves as the first impression for your contributors.

Here are some things to consider inside your `README.md`:

Expand All @@ -17,7 +17,7 @@ Here are some things to consider inside your `README.md`:
- link to the open source license
- link to community Discord, Slack group or GitHub discussions

A `README.md` is written in a markup language called [markdown](https://www.markdownguide.org/). This is a popular language used in open source documentation like README's.
A `README.md` is written in a markup language called [Markdown](https://www.markdownguide.org/). This is a popular language used in open source documentation like README's.

Here are a few examples of good `README.md` files:

Expand All @@ -27,7 +27,7 @@ Here are a few examples of good `README.md` files:

## How to Write an Installation Guide for Contributors

When a new contributor is interested in working with your project, they will need a clear step by step guide on how to setup everything locally. This guide should include the following items:
When a new contributor is interested in working with your project, they will need a clear step-by-step guide on how to set up everything locally. This guide should include the following items:

- instructions for forking the repository
- instructions for cloning the repository
Expand All @@ -37,21 +37,21 @@ When a new contributor is interested in working with your project, they will nee
- instructions for running the project locally
- instructions for setting up Docker containers if applicable

The best way to test your guide is by setting up the project locally using your guide. You will learn quickly if anything is missing or not clear if you run into issues getting your project to work.
The best way to test your guide is by setting up the project locally using your guide. You will learn quickly if anything needs to be added or clarified if you encounter issues getting your project to work.

### Where to Place the Installation Guide

The best place for installation instructions should be in your project's `README.md` file. This will be the most accessible file for your contributors. It would good to have a section at the top for setting up the project locally.
The best place for installation instructions should be at the top of your project's `README.md` file, as it is the most accessible file for your contributors.

Another good place would be in the `CONTRIBUTING.md` file. This file is used to cover topics like installation setup, testing, linting, workflows, etc. You can place the installation instruction towards the top of your `CONTRIBUTING.md` file.
Another good place would be in the `CONTRIBUTING.md` file. This file covers topics like installation setup, testing, linting, workflows, etc. You can place the installation instructions towards the top of your `CONTRIBUTING.md` file.

If your project is on the larger side, then you might consider having a separate documentation site and dedicating a section for installation in there. You can use documentation site generators like [docsify](https://docsify.js.org/#/), [Docusaurus](https://docusaurus.io/) or [Starlight](https://starlight.astro.build/).
If your project is on the larger side, you might consider having a separate documentation site and dedicating a section for installation there. You can use documentation site generators like [docsify](https://docsify.js.org/#/), [Docusaurus](https://docusaurus.io/), or [Starlight](https://starlight.astro.build/).

## How to Choose a License for Your Project

An open source software license dictates how others can use, modify or distribute your software. Every project should have a clearly defined license within a `LICENSE.md` file. This file is usually located in the root directory so it is easily accessible by everyone.

Some licenses are more restrictive like the GNU GPL (General Public License) while others are less restrictive like the MIT license. Here are a few examples of licenses for OpenSauced projects:
Some licenses are more restrictive, like the GNU GPL (General Public License), while others are less restrictive, like the MIT license. Here are a few examples of licenses for OpenSauced projects:

- [OpenSauced Docs - MIT license](https://github.com/open-sauced/docs/blob/main/LICENSE)
- [OpenSauced App - Apache License 2.0](https://github.com/open-sauced/app/blob/beta/LICENSE)
Expand All @@ -60,21 +60,21 @@ To get a better understanding on which license would be work best for your proje

## How to Write a Code Of Conduct

A code of conduct is an established set of rules and behaviors that all open source participants agree to abide by. This document helps to ensure a healthy and inclusive environment for all involved with the project.
A Code of Conduct is an established set of rules and behaviors that all open source participants agree to abide by. This document helps to ensure a healthy and inclusive environment for all involved with the project.

This set of rules and expectations, will go in inside a `CODE_OF_CONDUCT.md` file in the root directory of your project. Most Code of Conducts are broken up into three categories: pledge, standards, and enforcement.
This set of rules and expectations will go in inside a `CODE_OF_CONDUCT.md` file in the root directory of your project. Most Code of Conducts are broken up into three categories: pledge, standards, and enforcement.

### Project pledge
### Project Pledge

The opening pledge is a statement of the type of environment that the project wants to create. Here is an excerpt from the [OpenSauced Code of conduct](https://github.com/open-sauced/.github/blob/main/CODE_OF_CONDUCT.md):
The opening pledge is a statement of the type of environment that the project wants to create. Here is an excerpt from the [OpenSauced Code of Conduct](https://github.com/open-sauced/.github/blob/main/CODE_OF_CONDUCT.md):

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

### Project standards
### Project Standards

The standards section explicitly lays out what is considered acceptable and non acceptable behavior by all project participants.
The standards section explicitly lays out what is considered acceptable and non-acceptable behavior by all project participants.

Here is an example from the [OpenSauced Code of conduct](https://github.com/open-sauced/.github/blob/main/CODE_OF_CONDUCT.md):
Here is an example from the [OpenSauced Code of Conduct](https://github.com/open-sauced/.github/blob/main/CODE_OF_CONDUCT.md):

Examples of behavior that contributes to creating a positive environment
include:
Expand All @@ -96,23 +96,23 @@ Examples of unacceptable behavior by participants include:
- Other conduct which could reasonably be considered inappropriate in a
professional setting

### Project enforcement
### Project Enforcement

If any member of the project is behaving in a unacceptable way that violates your Code of conduct, then you will want to explicitly state what will happen in that situation.
If any member of the project is behaving in an unacceptable way that violates your Code of Conduct, then you will want to state explicitly what will happen in that situation.

Here is an example from the [OpenSauced Code of conduct](https://github.com/open-sauced/.github/blob/main/CODE_OF_CONDUCT.md):
Here is an example from the [OpenSauced Code of Conduct](https://github.com/open-sauced/.github/blob/main/CODE_OF_CONDUCT.md):

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.

### Contributor Covenant

The Contributor Covenant is a code of conduct that you can use and adapt for your open source projects. To learn more, please visit their [website](https://www.contributor-covenant.org/).
The Contributor Covenant is a Code of Conduct you can use and adapt for your open source projects. To learn more, please visit their [website](https://www.contributor-covenant.org/).

## How create Contributing Guides
## How to Create Contributing Guides

A `CONTRIBUTING.md` file, is a guide on how contributors can help with your project. This file is usually located in the root directory of a project so it can be easily accessible by everyone.
A `CONTRIBUTING.md` file is a guide on how contributors can help with your project. This file is usually located in the root directory of a project so everyone can easily access it.

Your guide should include the following sections:

Expand All @@ -123,29 +123,29 @@ Your guide should include the following sections:
- guidelines for code and style conventions
- guidelines for creating pull requests

For an in depth look into how to create a strong `CONTRIBUTING.md` file, please read through this [OpenSauced article](https://dev.to/opensauced/how-to-make-a-delicious-contributing-guide-4bp3).
For an in-depth look into how to create a strong `CONTRIBUTING.md` file, please read through this [OpenSauced article](https://dev.to/opensauced/how-to-make-a-delicious-contributing-guide-4bp3).

## How to Create Issue Templates

Issue templates are helpful because you can guide your contributors on how to provide specific and structured information when opening issues in your project. This will help you make sure you are receiving the desired information in order to triage the issue correctly.
Issue templates are helpful because you can guide your contributors on how to provide specific and structured information when opening issues in your project. This will help you ensure you receive the desired information to triage the issue correctly.

You can create a variety of issue templates, like bug reports, feature requests, documentation updates, etc. Inside these templates, you can have required fields like steps on reproducing the bug or a details section for a feature request. You can also attach specific labels like "Needs triage", or "Bug" to certain types of issue templates.
You can create various issue templates, like bug reports, feature requests, documentation updates, etc. Inside these templates, you can have required fields like steps on reproducing the bug or a details section for a feature request. You can also attach specific labels like "Needs triage" or "Bug" to certain types of issue templates.

### How to Create Issue Templates Using GitHub's Template Builder

There are two ways to create issue templates. The first way is to use GitHub's template builder. For this option, you will need to go to your project's settings, navigate to the "Features" section and click on Set up templates. Here is a [detailed guide](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-templates) from the GitHub documentation.
There are two ways to create issue templates. The first way is to use GitHub's template builder. For this option, you will need to go to your project's settings, navigate to the "Features" section, and click on Set up templates. Here is a [detailed guide](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-templates) from the GitHub documentation.

### How to Create Issue Templates Using `yaml` Files

You can also create custom issue forms using `yaml`. You would start by creating a folder called `.github` in the root directory. Then you will need to add a folder inside there called `ISSUE_TEMPLATE`. (**Note**: It is important that this folder is in all caps or else it will not work on GitHub.)
You can also create custom issue forms using `yaml`. You would start by creating a folder called `.github` in the root directory. Then, you will need to add a folder inside there called `ISSUE_TEMPLATE`. (**Note**: It is important that this folder is in all caps, or else it will not work on GitHub.)

Inside the `ISSUE_TEMPLATE` folder, you can create different `yaml` files like a `bug.yml` or `feature.yml` file. Here is an [example bug report](https://raw.githubusercontent.com/open-sauced/.github/main/.github/ISSUE_TEMPLATE/bug_report.yml) used by OpenSauced.

To learn more about issue templates, please review the [documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) on GitHub.

## How to Create PR Templates

Similar to issue templates, pull request templates, allow you to guide your contributors on how to provide specific and structured information when opening pull requests in your project. This template will be in a file called `PULL_REQUEST_TEMPLATE.md` and it is usually located either in the root directory or the `.github` directory.
Similar to issue templates, pull request templates allow you to guide your contributors on how to provide specific and structured information when opening pull requests in your project. This template will be in a file called `PULL_REQUEST_TEMPLATE.md`, and it is usually located either in the root directory or the `.github` directory.

Here are a few things to consider inside your pull request template:

Expand All @@ -154,12 +154,12 @@ Here are a few things to consider inside your pull request template:
- section to link corresponding issue tickets to the PR (Ex. closes #123 or fixes #456)
- section to place screenshots and/recordings if applicable

Here is a example of a [good pull request template](https://raw.githubusercontent.com/open-sauced/.github/main/.github/PULL_REQUEST_TEMPLATE.md) used by OpenSauced. To learn more about creating pull request templates, please read through the [GitHub documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository).
Here is an example of a [good pull request template](https://raw.githubusercontent.com/open-sauced/.github/main/.github/PULL_REQUEST_TEMPLATE.md) used by OpenSauced. Please read through the [GitHub documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository) to learn more about creating pull request templates.

## How to Work with GitHub Project Boards

GitHub project boards are a way for you and your team to structure your list of issues. You can organize your issues in a classic [kanban](https://docs.github.com/en/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards) style by placing your issues in todo, in progress, in review and done columns. This will make it easy for you and your team to track the progress for upcoming releases and new feature work.
GitHub project boards are a way for you and your team to structure your list of issues. You can organize your issues in a classic [Kanban](https://docs.github.com/en/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards) style by placing your issues in the "Todo", "In Progress", and "Done" columns. This will make it easy for you and your team to track the progress of upcoming releases and new feature works.

To create a new project board for an individual repository, you can navigate to your GitHub profile and click on the projects tab. From there you will see a green "New project" button where you can create a new board and link it to a repository. You can also choose to make this board private to core maintainers or publicly visible to everyone.
To create a new project board for an individual repository, navigate to your GitHub profile and click the "Projects" tab. From there, you will see a green "New project" button where you can create a new board and link it to a repository. You can also choose to make this board private to core maintainers or publicly visible to everyone.

To learn more about GitHub project boards, please read through the [documentation](https://docs.github.com/en/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards).

0 comments on commit 46665e6

Please sign in to comment.