Some more details

docs/source/development/how-to.md

@@ -14,20 +14,20 @@ Assuming you have settled on contributing a small fix to the project, please rea
 {ref}`style_guide` on the next page before you continue.
 
 Next, clone the [repository](https://github.com/OpenSourceEconomics/estimagic/) to your
-local machine. This will create a copy of the repository where you have local write
-access. Your fix will be implemented in your copy. After that, you will open a Pull
-Request (PR). With a PR you propose your changes to be merged into the project. If you
-plan to become a regular contributor, we can give you push access to unprotected
-branches, which makes the process more convenient for you.
+local machine. This will create a copy of estimagic's repository where you have local
+write access. You'll implement all changes and fixes on your local copy before opening a
+Pull Request (PR). With a PR you propose your changes to be merged into the project's
+main branch. If you plan to become a regular contributor, we can give you push access to
+unprotected branches, which makes the process more convenient for you.
 
 Below is a step-by-step guide on how to implement your changes via a PR while adhering
 to estimagic's style guide.
 
 1. Clone the repository to your disk. Set up the project environment with conda. This
-   will automatically install your local version of estimagic in editable mode.
+   will automatically install a local version of estimagic in editable mode.
 
-   On your computer, open the terminal in the root of your local estimagic repo and
-   enter the following commands:
+   On your computer, open the terminal in the root directory of your local estimagic
+   repo and enter the following commands:
 
    ```bash
    $ conda env create -f environment.yml
@@ -47,17 +47,18 @@ to estimagic's style guide.
    $ git checkout -b YOUR_BRANCH
    ```
 
-   This assumes that you are on the estimagic main branch, which you are by default.
+   This assumes that you are on the local estimagic main branch, which you are by
+   default.
 
 1. Implement the fix or new feature. To stage your changes for commit, type
 
    ```bash
    $ git add src/estimagic/YOUR_FILE.py
    ```
 
-   To learn more about git and how to add/commit your local changes, have a look at the
-   materials
-   [here](https://effective-programming-practices.vercel.app/git/staging/objectives_materials.html).
+   To learn more about git and how to add/commit your local changes, have a look at
+   these
+   [online materials](https://effective-programming-practices.vercel.app/git/staging/objectives_materials.html).
 
 1. We validate contributions in two ways. First, we use a comprehensive test suite to
    check if your changes are compatible with estimagic. Second, we use
@@ -79,11 +80,11 @@ to estimagic's style guide.
    ```
 
    With pre-commit installed, linters are executed before each commit and the commit is
-   rejected if any of the checks fails. Note that some linters fix errors directly by
-   automatically modifying the code. Restage the respective files via
+   rejected if any of the checks fails. Note that some linters fix the errors
+   automatically by modifying the code in-place. Restage the respective files via
    `git add src/estimagic/YOUR_FILE.py`.
 
-   You can also run the linters manually via
+   You can also run the linters on the entire project via
 
    ```bash
    $ pre-commit run -a
@@ -99,10 +100,10 @@ to estimagic's style guide.
    ```
 
    ```bash
-   $ conda activate estimagic-docs`
+   $ conda activate estimagic-docs
    ```
 
-   Still in the `docs` folder, now build the sphinx documentation pages by typing
+   Still in the `docs` folder, type
 
    ```bash
    $ make html
@@ -117,19 +118,24 @@ to estimagic's style guide.
 
    and check if everything looks fine. Note that the command above opens the index page,
    from where you can navigate to other sections of the estimagic documentation. If you
-   wish to directly open a specific documentation page, you can type
+   wish to directly open a specific page, you can type
 
    ```bash
    $ google-chrome build/html/explanations/optimization/why_optimization_is_hard.html
    ```
 
-1. If all tests and pre-commit hooks have passed locally, you are ready to push your
-   changes to a new branch on the remote estimagic repository.
+1. If all tests and pre-commit hooks pass locally, you are ready to push your changes to
+   a new branch on the remote estimagic repository:
 
-   Go to estimagic's Github page. A banner will be displayed asking you whether you
-   would like to create a pull request. Click on the link and follow the instructions of
-   the PR template. Fill out the PR form to inform everyone what you have been working
-   on, what you have been trying to accomplish, and what you have done to achieve that.
+   ```bash
+   $ git push --set-upstream origin YOUR_BRANCH
+   ```
+
+   After setting up the new upstream branch, go to estimagic's Github page. A banner
+   will be displayed asking you whether you would like to create a pull request. Click
+   on the link and follow the instructions of the PR template. Fill out the PR form to
+   inform everyone what you have been working on, what you have been trying to
+   accomplish, and what you have done to achieve it.
 
    Opening a PR starts a complete run of the test suite on a Continuous Integration (CI)
    server. The status of the CI run is shown on your PR page. If necessary, make
@@ -138,5 +144,5 @@ to estimagic's style guide.
 1. Ask one of the main contributors to review your changes. If they have any remarks or
    suggestions, address them and commit your modifications.
 
-1. Once you're PR is approved, one your the main contributors will merge it into
+1. Once you're PR is approved, one of the main contributors will merge it into
    estimagic's main branch.