From 9a2654addc51406cdda86f5bd67bcdb3e93650df Mon Sep 17 00:00:00 2001 From: Sashank Date: Thu, 21 Aug 2025 12:48:44 +0530 Subject: [PATCH 01/21] Make CHANGES.rst requirement more prominent in contributing docs - Add clear warning that changelog entry is required and enforced by CI - Provide example format for different change types - Restructure PR requirements section for better visibility Fixes #890 --- CONTRIBUTING.rst | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 8948763..2a9fa59 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -13,14 +13,31 @@ These are some contribution examples - Sponsor a Sprint (https://plone.org/events/sprints/whatis). -For pull requests, keep this in mind ------------------------------------- +Pull Request Requirements +------------------------- -- Add a test which proves your fix and make it pass. +**Important:** Every pull request must include a changelog entry, or it will fail CI checks. -- Describe your change in ``CHANGES.rst`` +Before submitting your PR, ensure you have: -- Add yourself to the ``docs/credits.rst`` +1. **Add a changelog entry to ``CHANGES.rst``** - This is required and enforced by CI +2. Add a test which proves your fix and make it pass +3. Add yourself to ``docs/credits.rst`` + +Changelog Entry Format +~~~~~~~~~~~~~~~~~~~~~ + +Add your entry under the appropriate section in ``CHANGES.rst``: + +- **Minor changes:** For bug fixes, small improvements, refactoring +- **Breaking changes:** For changes that break existing API +- **New features:** For new functionality + +Example:: + + Minor changes: + + - Fix issue with timezone parsing in special cases. See `Issue XXX `_. Setup for Development --------------------- From 5fd0ee2ff5b3231c20fa065933fff85bf279da05 Mon Sep 17 00:00:00 2001 From: Sashank Date: Thu, 21 Aug 2025 12:53:20 +0530 Subject: [PATCH 02/21] Implement comprehensive solution for making CHANGES.rst requirement visible MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create PR template with prominent changelog requirement and checklist - Add .github/CONTRIBUTING.md pointing to docs with changelog reminder - Update README.rst to highlight changelog requirement for PRs - Improve CONTRIBUTING.rst with clear warning and formatting examples This addresses all aspects mentioned in issue #890: - README.rst contributing section ✓ - CONTRIBUTING.md file ✓ - PR template ✓ Follows stevepiercy's guidance on pointing to single authoritative source while making the changelog requirement impossible to miss. Fixes #890 --- .github/CONTRIBUTING.md | 5 +++++ .github/pull_request_template.md | 26 ++++++++++++++++++++++++++ README.rst | 2 +- 3 files changed, 32 insertions(+), 1 deletion(-) create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/pull_request_template.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..6f03808 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,5 @@ +# Contributing + +See our [contributing guidelines](https://icalendar.readthedocs.io/en/latest/contributing.html) for complete information on how to contribute to icalendar. + +**Quick reminder:** All pull requests must include a changelog entry in `CHANGES.rst` or they will fail CI checks. \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..f062291 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,26 @@ +## Important: Changelog Entry Required + +**All pull requests must include a changelog entry or they will fail CI checks.** + +Please add an entry to `CHANGES.rst` under the appropriate section: +- **Minor changes:** For bug fixes, improvements, refactoring +- **Breaking changes:** For changes that break existing API +- **New features:** For new functionality + +--- + +## Pull Request Details + +**Fixes #** (issue number) + +**Description:** + + +**Checklist:** +- [ ] Added entry to `CHANGES.rst` +- [ ] Added/updated tests +- [ ] Added myself to `docs/credits.rst` +- [ ] All tests pass locally + +**Additional Information:** + \ No newline at end of file diff --git a/README.rst b/README.rst index 74f3344..7b0944b 100644 --- a/README.rst +++ b/README.rst @@ -187,7 +187,7 @@ Further Reading You can find out more about this project: -* `Contributing`_ +* `Contributing`_ - **Note: All PRs must include a changelog entry** * `Changelog`_ * `License`_ From bed483f50e6e1f31be288829b3c40d3aad9d7111 Mon Sep 17 00:00:00 2001 From: Sashank Date: Thu, 21 Aug 2025 13:03:52 +0530 Subject: [PATCH 03/21] Add CHANGES.rst entry for contributing documentation improvements - Document the enhancement to make changelog requirement more visible - References Issue #890 - Follows established changelog format --- CHANGES.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES.rst b/CHANGES.rst index 3d1540e..ebd4ade 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -25,6 +25,7 @@ Minor changes: - Add improved setters for ``start``, ``duration``, and ``end`` properties with explicit locking mechanisms to provide more flexible property manipulation while maintaining RFC 5545 compliance. The implementation includes comprehensive test coverage to ensure proper behavior and backward compatibility. - Add ``new()`` method to ``vCalAddress`` class for consistent API usage. The method supports all RFC 5545 parameters including ``CN``, ``CUTYPE``, ``DELEGATED-FROM``, ``DELEGATED-TO``, ``DIR``, ``LANGUAGE``, ``PARTSTAT``, ``ROLE``, ``RSVP``, and ``SENT-BY``, with automatic ``mailto:`` prefix handling. See `Issue 870 `_. - Refactor ``set_duration`` methods in ``Event`` and ``Todo`` classes to eliminate code duplication by extracting common logic into shared ``set_duration_with_locking()`` function in ``icalendar.attr``. See `Issue 886 `_. +- Make ``CHANGES.rst`` requirement more prominent in contributing documentation by adding PR template, updating README.rst, and enhancing CONTRIBUTING.rst with clear CI enforcement warnings. See `Issue 890 `_. - Make coverage submission optional for CI Breaking changes: From 4a8a53667e720f3b38549c2aac6f2bd168e34351 Mon Sep 17 00:00:00 2001 From: Sashank Date: Thu, 21 Aug 2025 13:09:02 +0530 Subject: [PATCH 04/21] Complete documentation improvements with proper formatting - Add missing 'Bug fixes' section to changelog documentation - Fix line length issues in .github/CONTRIBUTING.md - Ensure all files follow project formatting standards - All RST and Markdown syntax validated --- .github/CONTRIBUTING.md | 6 ++++-- .github/pull_request_template.md | 3 ++- CONTRIBUTING.rst | 3 ++- 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 6f03808..f95410a 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,5 +1,7 @@ # Contributing -See our [contributing guidelines](https://icalendar.readthedocs.io/en/latest/contributing.html) for complete information on how to contribute to icalendar. +See our [contributing guidelines](https://icalendar.readthedocs.io/en/latest/contributing.html) +for complete information on how to contribute to icalendar. -**Quick reminder:** All pull requests must include a changelog entry in `CHANGES.rst` or they will fail CI checks. \ No newline at end of file +**Quick reminder:** All pull requests must include a changelog entry in +`CHANGES.rst` or they will fail CI checks. \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f062291..f917189 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -3,9 +3,10 @@ **All pull requests must include a changelog entry or they will fail CI checks.** Please add an entry to `CHANGES.rst` under the appropriate section: -- **Minor changes:** For bug fixes, improvements, refactoring +- **Minor changes:** For improvements, refactoring, documentation updates - **Breaking changes:** For changes that break existing API - **New features:** For new functionality +- **Bug fixes:** For bug fixes and error corrections --- diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 2a9fa59..2ed2dee 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -29,9 +29,10 @@ Changelog Entry Format Add your entry under the appropriate section in ``CHANGES.rst``: -- **Minor changes:** For bug fixes, small improvements, refactoring +- **Minor changes:** For small improvements, refactoring, documentation updates - **Breaking changes:** For changes that break existing API - **New features:** For new functionality +- **Bug fixes:** For bug fixes and error corrections Example:: From 6e4c7a085c6863712238321d6fa22a5094572f1e Mon Sep 17 00:00:00 2001 From: Sashank Date: Thu, 21 Aug 2025 13:23:56 +0530 Subject: [PATCH 05/21] Fix trailing space in PR template checklist - Remove trailing space after CHANGES.rst for consistency - Addresses Copilot AI review feedback --- .github/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f917189..fc76aa6 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -18,7 +18,7 @@ Please add an entry to `CHANGES.rst` under the appropriate section: **Checklist:** -- [ ] Added entry to `CHANGES.rst` +- [ ] Added entry to `CHANGES.rst` - [ ] Added/updated tests - [ ] Added myself to `docs/credits.rst` - [ ] All tests pass locally From fe0db72e26ef4ed3c8186476f173313ff4ebd29f Mon Sep 17 00:00:00 2001 From: Sashank Date: Thu, 21 Aug 2025 13:51:42 +0530 Subject: [PATCH 06/21] Sort contributors alphabetically while preserving maintainers at top - Keep Johannes Raggam (Maintainer) and Max M (Original author) at top - Sort remaining 77 contributors alphabetically by first name - All contributors preserved, no one lost in reordering - Improves maintainability and makes it easier to find contributors --- docs/credits.rst | 70 +++++++++++++++++++++++------------------------- 1 file changed, 33 insertions(+), 37 deletions(-) diff --git a/docs/credits.rst b/docs/credits.rst index ea5dd85..fe2f582 100644 --- a/docs/credits.rst +++ b/docs/credits.rst @@ -3,22 +3,37 @@ icalendar contributors - Johannes Raggam (Maintainer) - Max M (Original author) +- Abe Hanoka +- Alexander Pitkin - Andreas Zeidler +- Andreas Ruppen - Andrey Nikolaev - Barak Michener +- Bastian Wegge - Christian Geier - Christophe de Vienne +- cillianderoiste +- Clive Stevens - Dai MIKURUBE +- Dalton Durst - Dan Stovall +- David Venhoff - Eric Hanchrow - Eric Wieser - Erik Simmler +- Felix Stupp +- fitnr - George V. Reilly +- hajdbo +- ilya +- jacadzaca - Jannis Leidel +- Jeffrey Whewhetu - Jeroen F.J. Laros - Jeroen van Meeuwen (Kolab Systems) - Jochen Sprickerhof - Jordan Kiang +- Kamil Mańkowski - Klaus Klein - Laurent Lasudry - Lennart Regebro @@ -27,60 +42,41 @@ icalendar contributors - Markus Unterwaditzer - Martijn Faassen - Martin Melin +- Matt Lewis +- Maurits van Rees +- Mauro Amico - Michael Smith +- Michał Górny - Mikael Frykholm +- `Natasha Mattson `_ +- `Nicco Kunzmann `_ +- `NikEasY `_ - Olivier Grisel - Pavel Repin - Pedro Ferreira +- Pronoy - Rembane - Robert Niederreiter +- Robert Spralja - Rok Garbas - Ronan Dunklau - Russ - `Sashank Bhamidi `_ +- `Serif OZ `_ - Sidnei da Silva +- `Soham Dutta `_ +- spanktar - Stanislav Láznička - Stanislav Ochotnicky - Stefan Schwarzer +- `Steve Piercy `_ +- `Tariq `_ +- tgecho - Thomas Bruederli - Thomas Weißschuh +- tisto +- Tobias Brox +- TomTry - Victor Varvaryuk - Ville Skyttä - Wichert Akkerman -- cillianderoiste -- fitnr -- hajdbo -- ilya -- spanktar -- tgecho -- tisto -- TomTry -- Andreas Ruppen -- Clive Stevens -- Dalton Durst -- Kamil Mańkowski -- Tobias Brox -- `Nicco Kunzmann `_ -- Robert Spralja -- Maurits van Rees -- jacadzaca -- Mauro Amico -- Alexander Pitkin -- Michał Górny -- Pronoy -- Abe Hanoka -- `Natasha Mattson `_ -- `NikEasY `_ -- Matt Lewis -- Felix Stupp -- Bastian Wegge -- `Steve Piercy `_ -- Jeffrey Whewhetu -- `Soham Dutta `_ -- `Serif OZ `_ -- David Venhoff -- `Tariq `_ - -Find out who contributed:: - - $ git shortlog -s -e From 2e3d9df4af3b13168976862c6d5f040f8b86badc Mon Sep 17 00:00:00 2001 From: Sashank Date: Fri, 22 Aug 2025 20:19:56 +0530 Subject: [PATCH 07/21] Address niccokunzmann's review feedback - Restore missing 'Find out who contributed' section in credits.rst - Move PR template instructions to HTML comment - Simplify PR template: remove helper text, make tests optional - Reduce duplication in .github/CONTRIBUTING.md by removing CI reminder - All changes maintain functionality while improving maintainer experience --- .github/CONTRIBUTING.md | 5 +---- .github/pull_request_template.md | 22 ++++++---------------- docs/credits.rst | 4 ++++ 3 files changed, 11 insertions(+), 20 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index f95410a..98e7fd1 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,7 +1,4 @@ # Contributing See our [contributing guidelines](https://icalendar.readthedocs.io/en/latest/contributing.html) -for complete information on how to contribute to icalendar. - -**Quick reminder:** All pull requests must include a changelog entry in -`CHANGES.rst` or they will fail CI checks. \ No newline at end of file +for complete information on how to contribute to icalendar. \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index fc76aa6..891737e 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,27 +1,17 @@ -## Important: Changelog Entry Required + -**All pull requests must include a changelog entry or they will fail CI checks.** - -Please add an entry to `CHANGES.rst` under the appropriate section: -- **Minor changes:** For improvements, refactoring, documentation updates -- **Breaking changes:** For changes that break existing API -- **New features:** For new functionality -- **Bug fixes:** For bug fixes and error corrections - ---- - -## Pull Request Details - -**Fixes #** (issue number) +**Fixes #** **Description:** **Checklist:** - [ ] Added entry to `CHANGES.rst` -- [ ] Added/updated tests +- [ ] Added/updated tests (if applicable) - [ ] Added myself to `docs/credits.rst` -- [ ] All tests pass locally +- [ ] All tests pass **Additional Information:** \ No newline at end of file diff --git a/docs/credits.rst b/docs/credits.rst index fe2f582..dcb34d2 100644 --- a/docs/credits.rst +++ b/docs/credits.rst @@ -80,3 +80,7 @@ icalendar contributors - Victor Varvaryuk - Ville Skyttä - Wichert Akkerman + +Find out who contributed:: + + $ git shortlog -s -e From 41b9ccd9d89c948b24f5a92ee142e38b88f04dfd Mon Sep 17 00:00:00 2001 From: Sashank Date: Fri, 22 Aug 2025 20:42:32 +0530 Subject: [PATCH 08/21] Fix URL consistency: use /latest/ instead of /stable/ - Ensures all documentation links point to the same version - Maintains consistency with .github/CONTRIBUTING.md --- .github/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 891737e..6595c59 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,5 +1,5 @@ **Fixes #** From cc5dc2adea3bf5e92121f9e7bbe8ed45a0bb6b0d Mon Sep 17 00:00:00 2001 From: Sashank Date: Fri, 22 Aug 2025 20:52:44 +0530 Subject: [PATCH 09/21] Update docs/credits.rst Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/credits.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/credits.rst b/docs/credits.rst index dcb34d2..c6fb9af 100644 --- a/docs/credits.rst +++ b/docs/credits.rst @@ -62,7 +62,7 @@ icalendar contributors - Ronan Dunklau - Russ - `Sashank Bhamidi `_ -- `Serif OZ `_ +- `Serif OZ `_ - Sidnei da Silva - `Soham Dutta `_ - spanktar From e9fcc0977633d5ccb462a72ca8c13d88a197f429 Mon Sep 17 00:00:00 2001 From: Sashank Date: Thu, 28 Aug 2025 07:42:35 +0530 Subject: [PATCH 10/21] Address stevepiercy review feedback - Move CONTRIBUTING.md to root and merge with .rst content - Update PR template with headings, remove HTML comments - Fix changelog entry wording - Revert redundant README change - Remove duplicate contributing files --- .github/CONTRIBUTING.md | 4 --- .github/pull_request_template.md | 26 ++++++++--------- CHANGES.rst | 2 +- CONTRIBUTING.md | 42 +++++++++++++++++++++++++++ CONTRIBUTING.rst | 49 -------------------------------- README.rst | 2 +- 6 files changed, 56 insertions(+), 69 deletions(-) delete mode 100644 .github/CONTRIBUTING.md create mode 100644 CONTRIBUTING.md delete mode 100644 CONTRIBUTING.rst diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md deleted file mode 100644 index 98e7fd1..0000000 --- a/.github/CONTRIBUTING.md +++ /dev/null @@ -1,4 +0,0 @@ -# Contributing - -See our [contributing guidelines](https://icalendar.readthedocs.io/en/latest/contributing.html) -for complete information on how to contribute to icalendar. \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 6595c59..7137915 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,17 +1,15 @@ - +## Closes issue +Replace `ISSUE_NUMBER` with the issue number that your pull request fixes. Then GitHub will link and automatically close the related issue. +- [ ] Closes #ISSUE_NUMBER -**Fixes #** +## Description +Write a description of the fixes or improvements. -**Description:** - +## Checklist +- [ ] Added or updated tests if applicable. +- [ ] All tests pass locally. See https://icalendar.readthedocs.io/en/latest/install.html#running-tests. +- [ ] Added entry to `CHANGES.rst`. +- [ ] Added myself to `docs/credits.rst`. -**Checklist:** -- [ ] Added entry to `CHANGES.rst` -- [ ] Added/updated tests (if applicable) -- [ ] Added myself to `docs/credits.rst` -- [ ] All tests pass - -**Additional Information:** - \ No newline at end of file +## Additional information +Upload screenshots, videos, links to documentation, or any other relevant information. \ No newline at end of file diff --git a/CHANGES.rst b/CHANGES.rst index ebd4ade..5dd1905 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -25,7 +25,7 @@ Minor changes: - Add improved setters for ``start``, ``duration``, and ``end`` properties with explicit locking mechanisms to provide more flexible property manipulation while maintaining RFC 5545 compliance. The implementation includes comprehensive test coverage to ensure proper behavior and backward compatibility. - Add ``new()`` method to ``vCalAddress`` class for consistent API usage. The method supports all RFC 5545 parameters including ``CN``, ``CUTYPE``, ``DELEGATED-FROM``, ``DELEGATED-TO``, ``DIR``, ``LANGUAGE``, ``PARTSTAT``, ``ROLE``, ``RSVP``, and ``SENT-BY``, with automatic ``mailto:`` prefix handling. See `Issue 870 `_. - Refactor ``set_duration`` methods in ``Event`` and ``Todo`` classes to eliminate code duplication by extracting common logic into shared ``set_duration_with_locking()`` function in ``icalendar.attr``. See `Issue 886 `_. -- Make ``CHANGES.rst`` requirement more prominent in contributing documentation by adding PR template, updating README.rst, and enhancing CONTRIBUTING.rst with clear CI enforcement warnings. See `Issue 890 `_. +- Make ``CHANGES.rst`` requirement more prominent in contributing documentation by adding a pull request template, updating ``README.rst``, and enhancing ``CONTRIBUTING.rst`` with clear CI enforcement warnings. See `Issue 890 `_. - Make coverage submission optional for CI Breaking changes: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..793502b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,42 @@ +# Contributing + +See our [contributing guidelines](https://icalendar.readthedocs.io/en/latest/contributing.html) for complete information on how to contribute to icalendar. + +## Contribution examples + +- Reporting issues to the bugtracker. +- Submitting pull requests from a forked icalendar repo. +- Extending the documentation. +- Sponsor a Sprint (https://plone.org/events/sprints/whatis). + +## Pull request requirements + +> [!IMPORTANT] +> Every pull request must include a change log entry. + +Before submitting your pull request, ensure you have met the following requirements. + +1. **Add a changelog entry to `CHANGES.rst`** - This is required and enforced by CI +2. Add a test which proves your fix and make it pass +3. Add yourself to `docs/credits.rst` + +### Changelog entry format + +Add your entry under the appropriate section in `CHANGES.rst`: + +- **Minor changes:** For small improvements, refactoring, documentation updates +- **Breaking changes:** For changes that break existing API +- **New features:** For new functionality +- **Bug fixes:** For bug fixes and error corrections + +Example: + +``` +Minor changes: + +- Fix issue with timezone parsing in special cases. See `Issue XXX `_. +``` + +## Setup for development + +If you would like to setup icalendar to contribute changes, the [Installation Section](https://icalendar.readthedocs.io/en/latest/install.html) should help you further. \ No newline at end of file diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 2ed2dee..0000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,49 +0,0 @@ -You want to help and contribute? Perfect! -========================================= - -These are some contribution examples ------------------------------------- - -- Reporting issues to the bugtracker. - -- Submitting pull requests from a forked icalendar repo. - -- Extending the documentation. - -- Sponsor a Sprint (https://plone.org/events/sprints/whatis). - - -Pull Request Requirements -------------------------- - -**Important:** Every pull request must include a changelog entry, or it will fail CI checks. - -Before submitting your PR, ensure you have: - -1. **Add a changelog entry to ``CHANGES.rst``** - This is required and enforced by CI -2. Add a test which proves your fix and make it pass -3. Add yourself to ``docs/credits.rst`` - -Changelog Entry Format -~~~~~~~~~~~~~~~~~~~~~ - -Add your entry under the appropriate section in ``CHANGES.rst``: - -- **Minor changes:** For small improvements, refactoring, documentation updates -- **Breaking changes:** For changes that break existing API -- **New features:** For new functionality -- **Bug fixes:** For bug fixes and error corrections - -Example:: - - Minor changes: - - - Fix issue with timezone parsing in special cases. See `Issue XXX `_. - -Setup for Development ---------------------- - -If you would like to setup icalendar to -contribute changes, the `Installation Section -`_ -should help you further. diff --git a/README.rst b/README.rst index 7b0944b..74f3344 100644 --- a/README.rst +++ b/README.rst @@ -187,7 +187,7 @@ Further Reading You can find out more about this project: -* `Contributing`_ - **Note: All PRs must include a changelog entry** +* `Contributing`_ * `Changelog`_ * `License`_ From 183d88d44ef3d4e578a4315568ca21a24a7861ba Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 29 Aug 2025 20:54:38 -0700 Subject: [PATCH 11/21] Add line breaks for author legibility --- .github/pull_request_template.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7137915..dfc6b30 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,15 +1,20 @@ ## Closes issue + Replace `ISSUE_NUMBER` with the issue number that your pull request fixes. Then GitHub will link and automatically close the related issue. + - [ ] Closes #ISSUE_NUMBER ## Description + Write a description of the fixes or improvements. ## Checklist + - [ ] Added or updated tests if applicable. - [ ] All tests pass locally. See https://icalendar.readthedocs.io/en/latest/install.html#running-tests. - [ ] Added entry to `CHANGES.rst`. - [ ] Added myself to `docs/credits.rst`. ## Additional information -Upload screenshots, videos, links to documentation, or any other relevant information. \ No newline at end of file + +Upload screenshots, videos, links to documentation, or any other relevant information. From 8373bf962ee29c3b1d5c5287d2746c982d88d47a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 29 Aug 2025 20:58:04 -0700 Subject: [PATCH 12/21] Add second condition so that it applies to all contributors --- .github/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index dfc6b30..6b5effc 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,7 +13,7 @@ Write a description of the fixes or improvements. - [ ] Added or updated tests if applicable. - [ ] All tests pass locally. See https://icalendar.readthedocs.io/en/latest/install.html#running-tests. - [ ] Added entry to `CHANGES.rst`. -- [ ] Added myself to `docs/credits.rst`. +- [ ] I've added myself to `docs/credits.rst` as a contributor in this pull request or have done so previously. ## Additional information From 5a69ad149b058891537f169b7c6d075890d24746 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 29 Aug 2025 21:00:41 -0700 Subject: [PATCH 13/21] Change the voice to be explicitly that of the contributor --- .github/pull_request_template.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 6b5effc..2c3a96c 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -10,9 +10,9 @@ Write a description of the fixes or improvements. ## Checklist -- [ ] Added or updated tests if applicable. -- [ ] All tests pass locally. See https://icalendar.readthedocs.io/en/latest/install.html#running-tests. -- [ ] Added entry to `CHANGES.rst`. +- [ ] I've added or updated tests if applicable. +- [ ] I've run and ensured all tests pass locally by following [Running Tests](https://icalendar.readthedocs.io/en/latest/install.html#running-tests). +- [ ] I've added a change log entry to `CHANGES.rst`. - [ ] I've added myself to `docs/credits.rst` as a contributor in this pull request or have done so previously. ## Additional information From 1ee9f527aa3cb22806cef8f8e6285e388b9ba1c6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 29 Aug 2025 21:33:17 -0700 Subject: [PATCH 14/21] Update `credits.rst` with three classifications of contributors, an introduction, and how to find the complete list. --- docs/credits.rst | 49 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 42 insertions(+), 7 deletions(-) diff --git a/docs/credits.rst b/docs/credits.rst index c6fb9af..710f086 100644 --- a/docs/credits.rst +++ b/docs/credits.rst @@ -1,8 +1,34 @@ -icalendar contributors -====================== +Credits +======= + +When you contribute to icalendar, please add your name to this list of contributors. +Please use the format of your public identity as either your name or GitHub username, followed by the URL to your GitHub profile. +Do not use an email address, as those may get harvested or become invalid in the future. + +.. code-block:: rst + + - GivenName Surname _ + - github_username _ + +The following people have made contributions to icalendar. +We're grateful for their support. + +Maintainers +----------- + +- `Nicco Kunzmann `_ +- Johannes Raggam + + +Original author +--------------- + +- Max M + + +Contributors +------------ -- Johannes Raggam (Maintainer) -- Max M (Original author) - Abe Hanoka - Alexander Pitkin - Andreas Zeidler @@ -49,7 +75,6 @@ icalendar contributors - Michał Górny - Mikael Frykholm - `Natasha Mattson `_ -- `Nicco Kunzmann `_ - `NikEasY `_ - Olivier Grisel - Pavel Repin @@ -81,6 +106,16 @@ icalendar contributors - Ville Skyttä - Wichert Akkerman -Find out who contributed:: - $ git shortlog -s -e +Complete list +------------- + +Although this list might not be complete, as some contributors either didn't know that they could add their name to this file or didn't want to be added, you can find out who contributed to icalendar. + +On GitHub, from the icalendar home page, click the link [Contributors](https://github.com/collective/icalendar/graphs/contributors). + +Alternatively from your local git checkout, issue the following command, which prints a list of all contributors sorted by their name and commit email address, and the count of commits for each one. + +.. code-block:: shell + + git shortlog -s -e From fdd5552e67467b6a777d4fb651b12438b07f3caf Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 29 Aug 2025 21:35:45 -0700 Subject: [PATCH 15/21] Use proper format for `fitnr` --- docs/credits.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/credits.rst b/docs/credits.rst index 710f086..6fbd12f 100644 --- a/docs/credits.rst +++ b/docs/credits.rst @@ -48,7 +48,7 @@ Contributors - Eric Wieser - Erik Simmler - Felix Stupp -- fitnr +- `fitnr `_ - George V. Reilly - hajdbo - ilya From e57e536b8e441bba067e00f9250c5497a4780cf6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 30 Aug 2025 02:17:40 -0700 Subject: [PATCH 16/21] Fix indentation of docstring to prevent docutils error --- src/icalendar/cal/component.py | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/src/icalendar/cal/component.py b/src/icalendar/cal/component.py index 081f013..5cef8cb 100644 --- a/src/icalendar/cal/component.py +++ b/src/icalendar/cal/component.py @@ -551,16 +551,17 @@ class Component(CaselessDict): CREATED = single_utc_property( "CREATED", - """CREATED specifies the date and time that the calendar -information was created by the calendar user agent in the calendar -store. + """ + CREATED specifies the date and time that the calendar + information was created by the calendar user agent in the calendar + store. -Conformance: - The property can be specified once in "VEVENT", - "VTODO", or "VJOURNAL" calendar components. The value MUST be - specified as a date with UTC time. - -""", + Conformance: + The property can be specified once in "VEVENT", + "VTODO", or "VJOURNAL" calendar components. The value MUST be + specified as a date with UTC time. + + """, ) _validate_new = True From 0b4b6857c6c701deb1a7f8efcadad49f65ffe799 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 30 Aug 2025 02:43:51 -0700 Subject: [PATCH 17/21] Add documentation as a requirement for pull requests. --- .github/pull_request_template.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 2c3a96c..15b04c7 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -10,9 +10,10 @@ Write a description of the fixes or improvements. ## Checklist +- [ ] I've added a change log entry to `CHANGES.rst`. - [ ] I've added or updated tests if applicable. - [ ] I've run and ensured all tests pass locally by following [Running Tests](https://icalendar.readthedocs.io/en/latest/install.html#running-tests). -- [ ] I've added a change log entry to `CHANGES.rst`. +- [ ] I've added or edited documentation, both as docstrings to be rendered in the API documentation and narrative documentation, as necessary. - [ ] I've added myself to `docs/credits.rst` as a contributor in this pull request or have done so previously. ## Additional information From 3f22a295eed4c738becabbf159943bf8629c9c34 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 30 Aug 2025 02:46:30 -0700 Subject: [PATCH 18/21] Move and rewrite content from `CONTRIBUTING.md` to `docs/contributing.rst`. --- CONTRIBUTING.md | 41 +---------------------------- docs/contributing.rst | 61 ++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 59 insertions(+), 43 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 793502b..1028177 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,42 +1,3 @@ # Contributing -See our [contributing guidelines](https://icalendar.readthedocs.io/en/latest/contributing.html) for complete information on how to contribute to icalendar. - -## Contribution examples - -- Reporting issues to the bugtracker. -- Submitting pull requests from a forked icalendar repo. -- Extending the documentation. -- Sponsor a Sprint (https://plone.org/events/sprints/whatis). - -## Pull request requirements - -> [!IMPORTANT] -> Every pull request must include a change log entry. - -Before submitting your pull request, ensure you have met the following requirements. - -1. **Add a changelog entry to `CHANGES.rst`** - This is required and enforced by CI -2. Add a test which proves your fix and make it pass -3. Add yourself to `docs/credits.rst` - -### Changelog entry format - -Add your entry under the appropriate section in `CHANGES.rst`: - -- **Minor changes:** For small improvements, refactoring, documentation updates -- **Breaking changes:** For changes that break existing API -- **New features:** For new functionality -- **Bug fixes:** For bug fixes and error corrections - -Example: - -``` -Minor changes: - -- Fix issue with timezone parsing in special cases. See `Issue XXX `_. -``` - -## Setup for development - -If you would like to setup icalendar to contribute changes, the [Installation Section](https://icalendar.readthedocs.io/en/latest/install.html) should help you further. \ No newline at end of file +See our [contributing guide](https://icalendar.readthedocs.io/en/latest/contributing.html) for complete information on how to contribute to icalendar. diff --git a/docs/contributing.rst b/docs/contributing.rst index 2eabc81..5c66b30 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,5 +1,60 @@ ------------------- Contributing ------------------- +============ -.. include:: ../CONTRIBUTING.rst +This guide describes how to contribute to icalendar. + +Examples of how to contribute +----------------------------- + +- Report issues to the bugtracker. +- Submit pull requests from your fork of the icalendar repository. +- Extend the documentation. +- Sponsor development of icalendar through [Open Collective](https://opencollective.com/python-icalendar). + + +Pull request requirements +------------------------- + +Before submitting your pull request, ensure you have met the following requirements. + +#. Add a changelog entry to :file:`CHANGES.rst`. + This is required and enforced by CI. + See :ref:`change-log` for details. +#. Add a test which proves your fix and passes. +#. Run all tests to ensure your changes don't break any existing functionality. +#. Add or edit documentation, both as docstrings to be rendered in the API documentation and narrative documentation, as necessary. +#. Add yourself to :file:`docs/credits.rst`, if you haven't already done so. + + +.. _change-log: + +Change log entry format +``````````````````````` + +Add your entry under the appropriate section in :file:`CHANGES.rst`. + +Minor changes + For small improvements, refactoring, and documentation updates. + +Breaking changes + For changes that break the existing API. + +New features + For new functionality. + +Bug fixes + For bug fixes and error corrections. + +Example: + +.. code-block:: rst + + Minor changes: + + - Fix issue with timezone parsing in special cases. See `Issue XXX `_. + + +Set up for development +---------------------- + +If you would like to set up icalendar to contribute changes, :doc:`install` should help you further. From acba1dec26fea2711023e15a17825a77bdb720c8 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 30 Aug 2025 02:54:52 -0700 Subject: [PATCH 19/21] - Remove warning of duplicate headings - Align credits.rst with maintenance.rst for Maintainers --- docs/credits.rst | 5 +++-- docs/maintenance.rst | 9 ++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/credits.rst b/docs/credits.rst index 6fbd12f..d85a818 100644 --- a/docs/credits.rst +++ b/docs/credits.rst @@ -16,8 +16,9 @@ We're grateful for their support. Maintainers ----------- +- `@geier `_ +- `@jacadzaca `_ - `Nicco Kunzmann `_ -- Johannes Raggam Original author @@ -52,12 +53,12 @@ Contributors - George V. Reilly - hajdbo - ilya -- jacadzaca - Jannis Leidel - Jeffrey Whewhetu - Jeroen F.J. Laros - Jeroen van Meeuwen (Kolab Systems) - Jochen Sprickerhof +- Johannes Raggam - Jordan Kiang - Kamil Mańkowski - Klaus Klein diff --git a/docs/maintenance.rst b/docs/maintenance.rst index 8e5a1ff..9c0e9db 100644 --- a/docs/maintenance.rst +++ b/docs/maintenance.rst @@ -4,17 +4,16 @@ Maintenance The goal of this section is to make sure that the ``icalendar`` library receives a clear maintenance structure with it that is transparent. +icalendar Maintainers +--------------------- -Maintainers ------------ - -Currently, the maintainers are +Currently the maintainers are the following people. - `@geier `_ - `@jacadzaca `_ - `@niccokunzmann `_ -Maintainers need this: +Maintainers need the following. - ``Admin`` access to the `repository `_. These can be enabled by a current maintainer or an GitHub organisation administrator From c07a3dea7d2a77322f6ecdc8216a392a2b7fc469 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 30 Aug 2025 03:00:03 -0700 Subject: [PATCH 20/21] Fix `WARNING: Inline literal start-string without end-string. [docutils]` by adding an escaped space after an inline literal --- CHANGES.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 5dd1905..09dc5bb 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -113,7 +113,7 @@ Bug fixes: Bug fixes: -- Fix to permit TZID forward references to ``VTIMEZONE``s +- Fix to permit TZID forward references to ``VTIMEZONE``\ s - Stabelize timezone id lookup, see `Issue 780 `_. 6.1.2 (2025-03-19) @@ -720,7 +720,7 @@ New features: Bug fixes: -- Fix ``VTIMEZONE``s including RDATEs #234. [geier] +- Fix ``VTIMEZONE``\ s including RDATEs #234. [geier] 3.11.5 (2017-07-03) @@ -731,7 +731,7 @@ Bug fixes: - added an assertion that ``VTIMEZONE`` sub-components' DTSTART must be of type DATETIME [geier] -- Fix handling of ``VTIMEZONE``s with subcomponents with the same DTSTARTs and +- Fix handling of ``VTIMEZONE``\ s with subcomponents with the same DTSTARTs and OFFSETs but which are of different types [geier] @@ -743,7 +743,7 @@ Bug fixes: - Don't break on parameter values which contain equal signs, e.g. base64 encoded binary data [geier] -- Fix handling of ``VTIMEZONE``s with subcomponents with the same DTSTARTs. +- Fix handling of ``VTIMEZONE``\ s with subcomponents with the same DTSTARTs. [geier] From f118a3a12ff0783e623dab396dbc2fffabb8d4b9 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 31 Aug 2025 13:11:06 -0700 Subject: [PATCH 21/21] Simplify change log entry for human consumption. People can view the link for details. --- CHANGES.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGES.rst b/CHANGES.rst index 09dc5bb..a51cc2f 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -25,7 +25,7 @@ Minor changes: - Add improved setters for ``start``, ``duration``, and ``end`` properties with explicit locking mechanisms to provide more flexible property manipulation while maintaining RFC 5545 compliance. The implementation includes comprehensive test coverage to ensure proper behavior and backward compatibility. - Add ``new()`` method to ``vCalAddress`` class for consistent API usage. The method supports all RFC 5545 parameters including ``CN``, ``CUTYPE``, ``DELEGATED-FROM``, ``DELEGATED-TO``, ``DIR``, ``LANGUAGE``, ``PARTSTAT``, ``ROLE``, ``RSVP``, and ``SENT-BY``, with automatic ``mailto:`` prefix handling. See `Issue 870 `_. - Refactor ``set_duration`` methods in ``Event`` and ``Todo`` classes to eliminate code duplication by extracting common logic into shared ``set_duration_with_locking()`` function in ``icalendar.attr``. See `Issue 886 `_. -- Make ``CHANGES.rst`` requirement more prominent in contributing documentation by adding a pull request template, updating ``README.rst``, and enhancing ``CONTRIBUTING.rst`` with clear CI enforcement warnings. See `Issue 890 `_. +- Improve contributing documentation by adding a change log requirement, adding a pull request template, adding clear CI enforcement warnings, and updating ``README.rst``. See `Issue 890 `_. - Make coverage submission optional for CI Breaking changes: