Merge pull request #345 from datacarpentry/km/contributing-guide

Expand contributing guide with specific style guidelines

Author: uschille

CONTRIBUTING.md

@@ -14,6 +14,10 @@ your change proposal as promptly as we can, and help you become a member of our
 community. Everyone involved in [The Carpentries][cp-site] agrees to abide by
 our [code of conduct](CODE_OF_CONDUCT.md).
 
+### Who Should Contribute?
+
+Contributions to this lesson are welcome from anyone with an interest in the project.
+
 ### How to Contribute
 
 The easiest way to get started is to file an issue to tell us about a spelling
@@ -43,7 +47,7 @@ documentation][template-doc].
    to [The Workbench documentation][template-doc].
 
 
-### What to Contribute
+### What to Contribute (General)
 
 There are many ways to contribute, from writing new exercises and improving
 existing ones to updating or filling in the documentation and submitting [bug
@@ -58,7 +62,63 @@ are particularly valuable**: it's easy for people who have been using these
 lessons for a while to forget how impenetrable some of this material can be, so
 fresh eyes are always welcome.
 
-### What *Not* to Contribute
+### What to Contribute (This Lesson)
+
+Any contributions are welcome, particularly ideas for how the existing content could be
+improved or updated, and/or errors that need to be corrected. Comments on existing issues 
+and reviews of pull requests are similarly welcome.
+
+If you plan to submit a pull request, please open an issue
+(or comment on an existing thread) first to ensure that effort is not duplicated
+or spent making a change that will not be accepted by the Maintainers.
+
+#### Content / style guidelines
+- If you add an image / figure that was generated from Python code, please include this 
+  code in your PR under `episodes/fig/source`.
+
+- Use the terms in the table below, when referring to Python libraries within the lesson. 
+  The table gives two terms for each library: `Term for descriptive text` which should be 
+  used when discussing the library in plain English / full sentences and `Term for code` 
+  which should be used when referring to code (and within code).
+
+   | Python library  | Term for descriptive text | Term for code  |
+   | :-------------  | :-------------            | :------------- | 
+   | [scikit-image](https://scikit-image.org/)  | scikit-image  | `skimage` |
+   | [NumPy](https://numpy.org/)  | NumPy | `numpy` |
+   | [Matplotlib](https://matplotlib.org/) | Matplotlib | `matplotlib` |
+   | [imageio](https://imageio.readthedocs.io/en/stable/index.html) | imageio | `imageio` |
+
+
+- When importing scikit-image use:
+   ```python
+   import skimage as ski
+   ```
+   Therefore, to access specific functions, you need to use their submodule name. For example:
+
+   ```python
+   import skimage as ski
+
+   rr, cc = ski.draw.rectangle(start=(357, 44), end=(740, 720))
+   ```
+
+- For reading and writing images, use the [imageio](https://imageio.readthedocs.io/en/stable/index.html) 
+  library and avoid use of `skimage.io`. For example:
+   ```python
+   import imageio.v3 as iio
+
+   chair = iio.imread(uri="data/chair.jpg")  # read an image
+   iio.imwrite(uri="data/chair.tif", image=chair)  # write an image
+   ```
+  
+- Comments providing an overall description of a code snippet should use triple quotes `"""`, e.g.,
+   ```python
+   """Python script to load a colour image in grayscale"""
+
+   chair = iio.imread(uri="data/chair.jpg")
+   gray_chair = ski.color.rgb2gray(chair)
+   ```
+
+### What *Not* to Contribute (General)
 
 Our lessons already contain more material than we can cover in a typical
 workshop, so we are usually *not* looking for more concepts or tools to add to
@@ -72,6 +132,23 @@ platform. Our workshops typically contain a mixture of Windows, macOS, and
 Linux users; in order to be usable, our lessons must run equally well on all
 three.
 
+### What *Not* to Contribute (This Lesson)
+
+Although most contributions will be welcome at this stage of the curriculum's development,
+the time available to deliver the content in a training event is strictly limited
+and needs to be accounted for when considering the addition of any new content.
+If you want to suggest the addition of new content, especially whole new sections or episodes,
+please open an issue to discuss this with the Maintainers first and provide the following 
+information alongside a summary of the content to be added:
+
+1. A suggested location for the new content.
+2. An estimate of how much time you estimate the new content would require in training
+   (teaching + exercises).
+3. The [learning objective(s)][cldt-lo] of this new content.
+4. (optional, but strongly preferred)
+   A suggestion of which of the currently-used learning objectives could be
+   removed from the curriculum to make space for the new content.
+
 ### Using GitHub
 
 If you choose to contribute via GitHub, you may want to look at [How to
@@ -92,6 +169,14 @@ Each lesson has a team of maintainers who review issues and pull requests or
 encourage others to do so. The maintainers are community volunteers, and have
 final say over what gets merged into the lesson.
 
+#### Merging Policy
+
+Pull requests made to the default branch of this repository
+(from which the lesson site is built)
+can only be merged after at least one approving review from a Maintainer.
+Any Maintainer can merge a pull request that has received at least one approval,
+but they may prefer to wait for further input from others before merging.
+
 ### Other Resources
 
 The Carpentries is a global organisation with volunteers and learners all over
@@ -102,6 +187,7 @@ media, slack, newsletters, and email lists. You can also [reach us by
 email][contact].
 
 [repo]: https://github.com/datacarpentry/image-processing
+[cldt-lo]: https://carpentries.github.io/lesson-development-training/05-objectives.html#learning-objectives
 [contact]: mailto:team@carpentries.org
 [cp-site]: https://carpentries.org/
 [dc-issues]: https://github.com/issues?q=user%3Adatacarpentry

README.md

@@ -7,7 +7,7 @@ A lesson teaching foundational image processing skills with Python and [scikit-i
 
 ## Lesson Content
 
-This lesson introduces fundamental concepts in image handling and processing. Learners will gain the skills needed to load images into Python, to select, summarise, and modify specific regions in these image, and to identify and extract objects within an image for further analysis.
+This lesson introduces fundamental concepts in image handling and processing. Learners will gain the skills needed to load images into Python, to select, summarise, and modify specific regions in these images, and to identify and extract objects within an image for further analysis.
 
 The lesson assumes a working knowledge of Python and some previous exposure to the Bash shell.
 A detailed list of prerequisites can be found in [`learners/prereqs.md`](learners/prereqs.md).
@@ -16,6 +16,10 @@ A detailed list of prerequisites can be found in [`learners/prereqs.md`](learner
 
 - Make a suggestion or correct an error by [raising an Issue](https://github.com/datacarpentry/image-processing/issues).
 
+Please see the [CONTRIBUTING.md file](CONTRIBUTING.md) for contributing guidelines and details on how to get involved with 
+this project. Some specific guidelines for content / style are provided in the 
+['What to Contribute (This Lesson)' section](CONTRIBUTING.md#what-to-contribute-this-lesson).
+
 ## Code of Conduct
 
 All participants should agree to abide by the [The Carpentries Code of Conduct](https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html).