From 979c65459481f68cc6e1881334caa9ee943a9df1 Mon Sep 17 00:00:00 2001 From: Kimberly Meechan <24316371+K-Meech@users.noreply.github.com> Date: Tue, 10 Jun 2025 09:13:17 +0100 Subject: [PATCH 1/4] add style guidelines to contributing guide --- CONTRIBUTING.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 82 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c46743eb7..f0d8f47de 100644 --- a/CONTRIBUTING.md +++ b/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 curriculum 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,58 @@ 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. + +#### Style / content 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 + ``` + If you need a specific sub-module, reference this explicitly based on `ski`. 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 = skimage.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 +127,22 @@ 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 +163,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 +181,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 From 624a104df04d43c7f9c0b7077e8b6f703655c46d Mon Sep 17 00:00:00 2001 From: Kimberly Meechan <24316371+K-Meech@users.noreply.github.com> Date: Tue, 10 Jun 2025 09:23:56 +0100 Subject: [PATCH 2/4] link to contributing file from readme --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5f1ddd958..6580b10f6 100644 --- a/README.md +++ b/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](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). From 6272d041fe9930be300ddeafa462166bfee396d0 Mon Sep 17 00:00:00 2001 From: Kimberly Meechan <24316371+K-Meech@users.noreply.github.com> Date: Tue, 10 Jun 2025 09:46:53 +0100 Subject: [PATCH 3/4] small fixes to formatting --- CONTRIBUTING.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f0d8f47de..f2262ea06 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,11 +73,13 @@ If you plan to submit a pull request, please open an issue or spent making a change that will not be accepted by the Maintainers. #### Style / content guidelines -- If you add an image / figure that was generated from python code, please include this code in your PR under `episodes/fig/source`. +- 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). +- 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 | | :------------- | :------------- | :------------- | @@ -98,7 +100,8 @@ or spent making a change that will not be accepted by the Maintainers. 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: +- 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 @@ -133,7 +136,8 @@ Although most contributions will be welcome at this stage of the curriculum's de 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: +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 From 9293c50dc5af6bb972a8dfc56d24eb7823f7eeae Mon Sep 17 00:00:00 2001 From: Kimberly Meechan <24316371+K-Meech@users.noreply.github.com> Date: Sun, 15 Jun 2025 15:22:32 +0100 Subject: [PATCH 4/4] minor changes based on reviews --- CONTRIBUTING.md | 16 +++++++++------- README.md | 2 +- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f2262ea06..5ed47c067 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,7 @@ our [code of conduct](CODE_OF_CONDUCT.md). ### Who Should Contribute? -Contributions to this curriculum are welcome from anyone with an interest in the project. +Contributions to this lesson are welcome from anyone with an interest in the project. ### How to Contribute @@ -72,11 +72,11 @@ 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. -#### Style / content guidelines -- If you add an image / figure that was generated from python code, please include this +#### 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. +- 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). @@ -93,10 +93,11 @@ or spent making a change that will not be accepted by the Maintainers. ```python import skimage as ski ``` - If you need a specific sub-module, reference this explicitly based on `ski`. For example: + 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)) ``` @@ -104,16 +105,17 @@ or spent making a change that will not be accepted by the Maintainers. 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. +- 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 = skimage.color.rgb2gray(chair) + gray_chair = ski.color.rgb2gray(chair) ``` ### What *Not* to Contribute (General) diff --git a/README.md b/README.md index 6580b10f6..02f847b55 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ 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](CONTRIBUTING.md) for contributing guidelines and details on how to get involved with +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).