Update/fix instructions in README.md

Author: ischoegl

README.md

@@ -20,25 +20,45 @@ based only on the basic mechanisms provided in the main Cantera repository.
 
 ## Adding files for new examples
 
-To implement an example requiring a new input file, the following steps should be
-followed:
+To implement an example requiring a new input file, make sure to have forked both
+`Cantera/cantera` and `Cantera/cantera-example-data` repositories. Using the local Git
+checkouts of your personal fork, the following steps should be followed:
 
+### Create example and input file(s)
+
+- Create a new feature branch in your personal fork of the `cantera` repository.
 - Create your new example in your local Git checkout of Cantera.
-- Create the new input file in the `data/example_data` subdirectory.
-- Commit the example to a new feature branch.
-  * :warning: Make sure you _do not_ add the input file or an update of the
+- In the `data/example_data` subdirectory (a Git submodule), configure your fork of
+  `cantera-example-data` as a remote and create a feature branch for your input file.
+- Create the new input file(s) in the `data/example_data` subdirectory.
+- Test that your example performs as expected locally.
+
+### Commit new files to your forks
+
+- From within the `data/example_data` subdirectory, commit the input file(s) to your
+  feature branch in the `cantera-example-data` repository.
+- From the root folder, commit the example to a new feature branch and push to your
+  feature branch in the `cantera` repository.
+  * :warning: Make sure you _do not_ add the input file(s) or an update of the
     `example_data` submodule to this branch.
-- Commit the input file to a feature branch in the `example_data` submodule.
-- Create a pull request for your example in the main Cantera repository
+
+### Create pull requests on GitHub
+
+- Create a pull request for your example in the main Cantera repository.
+  * You should see multiple failing jobs. For new Python examples, descriptions start
+    with `CI / Run Python 3.XX examples on ubuntu-YY.ZZ` for tests with different
+    Python and ubuntu versions. For examples using other Cantera APIs, multiple other CI
+    jobs may fail.
 - Create a pull request in the `cantera-example-data` repository which includes the
   reference `Cantera/cantera#XYZ` in the title where `XYZ` is the number of your PR in
   the main repository.
-  * The CI process in the main repository will automatically check out this submodule
-    PR so the new input file is available for those jobs that run the examples.
-  * You should see one failing job, with the description `Linters / Check for unmerged
-    example-data pull request (pull_request)`. This is a reminder for maintainers for
-    the remaining steps that need to be completed before merging the PR.
-- Once PR reviews are completed and all expected tests pass, the PR on the
-  `cantera-example-data` can be merged.
+- Subsequent pushes to your feature branch on the main PR will result in the following:
+  * You should see one additional failing CI job, with the description `Linters / Check
+    for unmerged example-data pull request (pull_request)`. This is a reminder for
+    maintainers for the remaining steps that need to be completed before merging the PR.
+- Once the PR review of the `cantera-example-data` branch is completed, it will be
+  merged by maintainers.
 - Finally, the PR branch for the main repository can be updated to include the update
-  of the `example_data` submodule, and this PR can be merged.
+  of the `example_data` submodule, which should be reset to the official Cantera
+  `cantera-example-data` repository. At this point, all CI jobs should pass. Once the
+  PR review is completed, the PR is ready to be merged.