Contribute#

This guide describes how to contribute to icalendar.

Examples of how to contribute#

  • Report issues in the issue tracker.

  • Comment on and resolve issues.

  • Submit pull requests from your fork of the icalendar repository.

  • Extend the Documentation.

  • Sponsor development of icalendar through Open Collective.

First-time contributors#

Contributions to icalendar from people new to icalendar are welcome.

Like most free and open source software, icalendar promotes the "free" part, meaning freedom or liberty.

  • You're free to start work on issues without asking.

  • You're free to ask questions to clarify the scope of work before you start.

  • We don't assign issues.

  • Free other contributors from duplicating your effort by opening a pull request as soon as you can.

For people participating in programs to encourage first-time contributions, including Hacktoberfest, Good First Issue, and Up For Grabs, you must comply with their terms and conditions to receive their recognition or rewards. Accordingly, you may request of the maintainers in your pull request that you would like recognition for your contribution.

See also

Find open issues.

Good First Issue

Documentation

Hacktoberfest

Artificial intelligence policy#

We want to protect the joy, goodwill, and volunteer time of the maintainers and contributors of icalendar. As such, we take a strong stance against artificial intelligence (AI) abuse.

Contributors to icalendar must follow icalendar's AI policy as described in this section and its subsections.

Responsible AI use#

You may responsibly use AI as a tool to draft a pull request. That means you must comply with Pull request requirements and follow the Python Calendaring Ecosystem's Code of Conduct.

If you use AI in your work:

  • You must take responsibility for the output, including reviewing and validating the output for accuracy and ensuring it resolves an issue.

  • You must check the AI's terms of use, and ensure that outputs are not reconstructed from copyrighted sources.

  • You are expected to understand and be able to explain design and code decisions.

  • In your git commit messages, you must specify both (1) which AI model and version you used, and (2) how you used it, by either including the prompts and interactions you used or summarizing them.

  • You must disclose that you used AI in your change log entry.

  • You shall be held accountable for your AI-generated content.

AI abuse#

You may not abuse AI to generate a pull request that is disruptive to the icalendar community or does not adhere to Responsible AI use described in the previous subsection. Examples of such abuse and irresponsible use include the following actions.

  • You claim no responsibility for the output of AI generated content.

  • Your pull request demonstrates no understanding or thought whatsoever to solve an issue.

  • Your pull request plagiarizes copyrighted or other material to which you have no legal claim.

  • You ignore or don't respond to feedback.

  • The GitHub account is itself an AI agent.

Report suspected violations#

To report a suspected violation of this AI policy, see the Reporting an issue section in the Python Calendaring Ecosystem's Code of Conduct. The maintainers may close pull requests without providing feedback that they deem to be spam, AI slop, abuse, or that do not comply with pull request requirements. The maintainers may also take further action, including suspend, ban, or report GitHub users, as described in Python Calendaring Ecosystem's Code of Conduct.

Pull request requirements#

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 GitHub checks. See Change log entry format for details.

  2. Add a test which proves your fix and passes.

  3. Run all tests to ensure your changes don't break any existing functionality.

  4. Add or edit documentation, both as docstrings to be rendered in the API reference documentation and narrative documentation, as necessary.

The maintainers may close pull requests without providing feedback that they deem to be spam, AI slop, abuse, or that do not comply with pull request requirements. The maintainers may also take further action, including suspend, ban, or report GitHub users, as described in Python Calendaring Ecosystem's Code of Conduct.

Change log entry format#

Add your entry under the appropriate section in 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.

Documentation

For changes to the documentation, docstrings, spelling dictionary, or any other documentation matter.

Examples:

Minor changes:

- Fix issue with timezone parsing in special cases. :issue:`1050`

For a pull request, use the following syntax.

New features:

- Added :attr:`~icalendar.cal.calendar.Calendar.categories` property. :pr:`808`

Set up for development#

If you would like to set up icalendar to contribute changes, see Development.