Add instructions for creating news fragments; usage and style improve…

…ments
pdm-project · Aug 2, 2021 · be541cf · be541cf
1 parent 9f28d2b
commit be541cf
Showing 1 changed file with 22 additions and 12 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,13 +5,13 @@ First off, thanks for taking the time to contribute! Contributions include but a
 - Reporting bugs
 - Contributing to code
 - Writing tests
-- Writing documents
+- Writing documentation
 
 The following is a set of guidelines for contributing.
 
-## A recommended flow of contributing to an Open Source project.
+## A recommended flow of contributing to an Open Source project
 
-This guideline is for new beginners of OSS. If you are an experienced OSS developer, you can skip
+This section is for beginners to OSS. If you are an experienced OSS developer, you can skip
 this section.
 
 1. First, fork this project to your own namespace using the fork button at the top right of the repository page.
@@ -29,34 +29,38 @@ this section.
    where `fork` is the remote name of the fork repository.
 
 **ProTips:**
+
 1. Don't modify code on the main branch, the main branch should always keep track of origin/main.
 
    To update main branch to date:
+
    ```bash
    $ git pull origin main
    # In rare cases that your local main branch diverges from the remote main:
    $ git fetch origin && git reset --hard main
    ```
+
 2. Create a new branch based on the up-to-date main branch for new patches.
 3. Create a Pull Request from that patch branch.
 
 ## Local development
 
-To make sure the tests suites can run rightly, you need to install [Git LFS](https://git-lfs.github.com/), then
+To make sure the tests suites can run correctly, you need to install [Git LFS](https://git-lfs.github.com/), then
+
 ```bash
 $ git lfs install
 # If you have already cloned the repository, execute the below command as well.
 $ git lfs pull
 ```
 
-Then, you need to install base dependencies in a venv. Although PDM uses local package directory to install
-dependencies, venv is still needed to start up PDM at the first time:
+Then, you need to install base dependencies in a venv. Although PDM uses a local package directory to install
+dependencies, venv is still needed to start up PDM for the first time:
 
 ```bash
 $ python setup_dev.py
 ```
 
-Now, all dependencies are installed into local `__pypackages__` directory, which will be used for development
+Now, all dependencies are installed into the local `__pypackages__` directory, which will be used for development
 after this point. The `pdm` executable located at `__pypackages__/<VERSION>/bin` can be run directly from outside,
 which is installed in editable mode, or you can use `python -m pdm` from inside the venv.
 
@@ -66,24 +70,30 @@ which is installed in editable mode, or you can use `python -m pdm` from inside
 $ pdm run test
 ```
 
-The test suite is still simple and requires to be supplied, please help write more test cases.
+The test suite is still simple and needs expansion! Please help write more test cases.
 
 ### Code style
 
-PDM uses `pre-commit` for linting, you need to install `pre-commit` first, then:
+PDM uses `pre-commit` for linting. Install `pre-commit` first, then:
 
 ```bash
 $ pre-commit install
 $ pdm run lint
 ```
 
-PDM uses `black` coding style and `isort` for sorting import statements, if you are not following them,
-the CI will fail, and your Pull Request will not be merged.
+PDM uses `black` for code style and `isort` for sorting import statements. If you are not following them,
+the CI will fail and your Pull Request will not be merged.
+
+### News fragments
 
+When you make changes such as fixing a bug or adding a feature, you must add a news fragment describing
+your change. News fragments are placed in the `news/` directory, and should be named according to this
+pattern: `<issue_num>.<issue_type>.md` (e.g., `566.bugfix.md`). The contents of the file should be a single sentence in the imperative
+mood that describes your changes. (e.g., `Deduplicate the plugins list.` ) See entries in the [change log](/changelog) for more examples.
 
 ### Preview the documentation
 
-If you do some changes to the `docs/` and you may want to preview the build result, simply do:
+If you make some changes to the `docs/` and you want to preview the build result, simply do:
 
 ```bash
 $ pdm run doc