From 55659315c62d45d9bb60b2a30ffd583bd998e183 Mon Sep 17 00:00:00 2001 From: Cotes Chung <11371340+cotes2020@users.noreply.github.com> Date: Sun, 1 Oct 2023 06:00:36 +0800 Subject: [PATCH] docs: update project docs --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- README.md | 12 +++---- docs/CONTRIBUTING.md | 57 +++++++++++++++++--------------- 3 files changed, 38 insertions(+), 33 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index db4eb1f..0ff984a 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,5 +1,5 @@ ## Type of change - + - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Improvement (refactoring and improving code) diff --git a/README.md b/README.md index 266f94a..75cb3bb 100644 --- a/README.md +++ b/README.md @@ -45,18 +45,18 @@ ## Documentation -To explore usage, development, and upgrade guide of the project, please refer to the [**Wiki**][wiki]. +To learn how to use, develop, and upgrade the project, please refer to the [Wiki][wiki]. ## Contributing -Contributions (_pull requests_, _issues_ and _discussions_) are what make the open source community such an amazing place +Contributions (_pull requests_, _issues_, and _discussions_) are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. For details, see the "[Contributing Guidelines][contribute-guide]". ## Credits -This theme is mainly built with [Jekyll][jekyllrb] ecosystem, -[Bootstrap][bootstrap], [Font Awesome][icons] and some other [wonderful tools][lib]. +This project is mainly built with [Jekyll][jekyllrb] ecosystem, +[Bootstrap][bootstrap], [Font Awesome][icons], and some other [wonderful tools][lib]. The avatar and favicon design come from [Clipart Max][image]. Many thanks to the [contributors][contributors] who participated in the development @@ -66,7 +66,7 @@ Last but not least, thanks to [JetBrains][jetbrains] for providing the _Open Sou ## Sponsoring -If you like this project, or have built something through it, please consider supporting me in the following ways. Any support would be greatly appreciated! +If you like this project, or have built something through it, please consider supporting this project. Any support would be greatly appreciated! [![Ko-fi](https://img.shields.io/badge/Support_Me_on_Ko--fi-ff5e5b?logo=ko-fi&logoColor=white)][ko-fi]  [![Wechat Pay](https://img.shields.io/badge/Support_Me_on_WeChat-brightgreen?logo=wechat&logoColor=white)][donation]  @@ -74,7 +74,7 @@ If you like this project, or have built something through it, please consider su ## License -This work is published under [MIT License][license]. +This project is published under [MIT License][license]. [gem]: https://rubygems.org/gems/jekyll-theme-chirpy [ci]: https://github.com/cotes2020/jekyll-theme-chirpy/actions/workflows/ci.yml?query=event%3Apush+branch%3Amaster diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index b86cb2d..63024c3 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,38 +1,41 @@ # Contributing Guidelines -:tada: _First of all, thank you for considering contributing to this project!_ :tada: +_First of all, thank you for considering contributing to this project_ ! :tada: There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug -reports and feature requests or writing code which can be incorporated into Chirpy itself. +reports and feature requests, or writing code that can be incorporated into the project. In order to make a good +experience for both contributors and maintainers, please start with the "[General Rules](#general-rules)" +before taking further action. -## In This Article +## Table of Contents - [General Rules](#general-rules) - [Questions and Requests for Help](#questions-and-requests-for-help) -- [File a Bug Report](#file-a-bug-report) -- [Suggest a New Feature](#suggest-a-new-feature) -- [Contributing Code and Documentation Changes](#contributing-code-and-documentation-changes) +- [Reporting a Bug](#reporting-a-bug) +- [Suggesting a New Feature](#suggesting-a-new-feature) +- [Contributing Code/Documentation](#contributing-codedocumentation) - [Helpful Resources](#helpful-resources) ## General Rules -All contributions should be based on the following rules: +All types of contributions (_pull requests_, _issues_, and _discussions_) should follow these rules: - You should read through the [Wiki][wiki] to understand the project features and how to use it properly. This is to respect the time of the project's developers and -maintainers, and to save their energy for other problems that really need to be resolved. +maintainers and to save their energy for other problems that really need to be resolved. - Use the [latest release version][latest-ver]. If your contribution involves code/documentation changes, update to the latest version of the default (`master`) branch. -- Avoid making duplicate contributions by searching for existing [Issues][issues] / [Discussioins][discus] / -[Pull Requests][pr], but don't leave any unhelpful comments such as "I have the same problem". Prefer using +- Avoid making duplicate contributions by searching for existing [issues][issues] / [discussions][discus] / +[pull requests][pr], but don't leave any unhelpful comments such as "I have the same problem". Prefer using [reactions][gh-reactions] if you simply want to "+1" an existing issue. - DO NOT email or tweet the -project developers and maintainers directly, everything about Chirpy should be left in GitHub. +project developers and maintainers directly, everything about the project should be left on GitHub. -**Tips**: If you're new to open source, see "[How To Ask Questions The Smart Way][ext-reading]". +**Tip**: If you are new to the open-source community, then please read through +"[How To Ask Questions The Smart Way][ext-reading]" before contributing. ## Questions and Requests for Help @@ -43,7 +46,7 @@ enthusiastic geeks who will positively answer your challenging questions. If you can't get an answer in any of the above ways, then create a new [discussion][discus]. As long as it is not a duplicate and [RTFM][rtfm] / [STFW][stfw] issue, we will respond as soon as possible. -## File a Bug Report +## Reporting a Bug A great way to contribute to the project is to send a detailed issue when you encounter a problem. We always appreciate a well-written, thorough bug report. @@ -58,34 +61,34 @@ You can learn about Jekyll and modern Web development to solve problems caused b 3. Make good use of your browser's incognito mode to troubleshoot if the problem is caused by caching. -4. As a last option, you can create a new [Bug Report][new-issue] follow the template to describe the details. +4. As a last option, you can create a new [Bug Report][bug-report] following the template to describe the details. If possible, providing a demo that reproduces the error will help us troubleshoot faster. -## Suggest a New Feature - -Feature requests are welcome! While we will consider all requests, we cannot guarantee your request will be accepted. - -We want to avoid chaos in the UI design, so we won't accept requests for changes like color schemes, font families, -typography, and so on. **Do not open a duplicate feature request.** Search for existing feature requests first. If you -find your feature (or one very similar) previously requested, comment on that issue. +## Suggesting a New Feature +Feature requests are welcome! While we will consider all requests, we cannot guarantee your request will be accepted. +We want to avoid chaos in the UI design and therefore do not accept requests for changes like color schemes, +fontfamilies, typography, and so on. We want to avoid [feature creep][feat-creep] and focus only on the core features. If accepted, we cannot make any commitments regarding the timeline for implementation and release. However, you are welcome to submit a pull request to help! -## Contributing Code and Documentation Changes +## Contributing Code/Documentation -In short, you can follow these steps to complete the contribution. +If your request is about an enhancement, it is recommended to first submit a +[Feature Request][feat-request] to discuss whether your idea fits the project. +See also: "[Suggesting a New Feature](#suggesting-a-new-feature)". Other than that, you can start the PR process. 1. Fork this project on GitHub and clone your repository locally. 2. Setting up the [development & test environments][dev-env]. -3. Create a new branch from the default branch and give it a descriptive name (e.g. `add-a-new-feat` or `fix-a-bug`). +3. Creating a new branch from the default branch and give it a descriptive name (e.g. `add-a-new-feat` or `fix-a-bug`). When development is complete, create a [Conventional Commit][cc] with Git. -4. Create a new [Pull Request][gh-pr]. +4. Submitting a [Pull Request][gh-pr]. ## Helpful Resources - [Code of conduct](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/docs/CODE_OF_CONDUCT.md) - [Security policy](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/docs/SECURITY.md) +- [How To Ask Questions The Smart Way][ext-reading] [latest-ver]: https://github.com/cotes2020/jekyll-theme-chirpy/releases/latest [wiki]: https://github.com/cotes2020/jekyll-theme-chirpy/wiki @@ -98,7 +101,9 @@ When development is complete, create a [Conventional Commit][cc] with Git. [rtfm]: https://en.wikipedia.org/wiki/RTFM [stfw]: https://www.webster-dictionary.org/definition/STFW [gh-reactions]: https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/ -[new-issue]: https://github.com/cotes2020/jekyll-theme-chirpy/issues/new/choose +[bug-report]: https://github.com/cotes2020/jekyll-theme-chirpy/issues/new?assignees=&labels=&projects=&template=bug_report.yml +[feat-request]: https://github.com/cotes2020/jekyll-theme-chirpy/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml +[feat-creep]: https://en.wikipedia.org/wiki/Feature_creep [dev-env]: https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Development-&-Test-Environments [cc]: https://www.conventionalcommits.org/ [gh-pr]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests