Instructions for AI agents

dateutil is a small project with very limited maintainer time. Read CONTRIBUTING.md before making changes; this file covers the things agents most often get wrong.

Before opening an issue or pull request

Search for existing work first, and include closed and merged items:

gh issue list --repo dateutil/dateutil --state all --search "<key words>"
gh pr list --repo dateutil/dateutil --state all --search "<key words>"
gh pr list --repo dateutil/dateutil --state all --search "<issue number>"

Try several phrasings: the same bug is often reported in terms of different functions (e.g. parse vs. parser.parser) or different time zones.

  • If an open pull request already addresses the problem, do not open another one. You may review or suggest improvements on the existing one, but only do so if you believe it would be meaningfully improved by your contributions.
  • If a merged pull request addresses it, check whether the problem still happens on master before going further.
  • If a closed pull request addresses it, read why it was closed so you do not repeat the same approach.
  • If an issue already exists, comment there (only if you have new information) rather than opening a new one.

Before reporting a bug, confirm it reproduces on the current master branch.

Issues

Follow the bug report guidance in CONTRIBUTING.md: a minimal, self-contained reproducer, the dateutil and Python versions, and what happens versus what you expected. For new features, open an issue for discussion before writing a pull request.

Pull requests

  • Use the pull request template. gh pr create --body, --fill, the REST API and MCP tools do not apply .github/pull_request_template.md for you. Read the template and fill it in; do not delete its sections or rewrite the checklist.
  • Only tick checklist items that are actually done.
  • Tests. Every change in behavior needs a test that fails without the fix. Test through the public API where possible.
  • Changelog. Add a news fragment in changelog.d/ named <number>.<type>.rst, where <type> is one of feature, bugfix, doc, deprecations, data or misc (see [tool.towncrier] in pyproject.toml). See the changelog section of CONTRIBUTING.md for the required wording, including the “Reported by” / “Fixed by” credits. Never invent an issue or PR number; if you do not have one yet, add the fragment after the PR is opened.
  • AUTHORS.md. If the person you are working for is not already listed in AUTHORS.md, add them, in alphabetical order, in the form - Name <email> (gh: @handle) **D**. Ask them how they want their name and e-mail to appear (the e-mail is optional); do not guess or use details from git config without asking.
  • Keep pull requests focused on one change. Do not include unrelated reformatting or refactoring.
  • AI attribution. Do not add Co-authored-by: trailers for an AI tool, in commits or in the PR description. If the user prefers to credit the tool, they may use an Assisted-by: trailer instead, e.g. Assisted-by: <agent name>:<model and version>.

IMPORTANT: How to write issues, PR descriptions and comments

The maintainers strongly prefer clear and concise communication. Avoid large blocks of text and front-load communications with concise information about what needs improvement, what the current behavior is and what you expect. For large amounts of background information or appendices, please use a details tag.

  • A PR description is a few sentences on what changed and why, plus Closes #N for the issue it fixes. The diff already shows what changed, so do not summarize it file by file.
  • Do not add filler sections such as “Summary”, “Overview” or “Key takeaways” on top of the template; the template already has the sections we want.
  • Do not state that tests, linting or type checks pass. CI reports that.
  • Describe the change, not the process. No “I'll”, “Let me” or narration of what the agent did or tried along the way.
  • No emoji decoration and no “Generated with ...” advertisements.
  • When replying to a review comment, answer the question that was asked, in as few words as it takes.

Additionally, please do not directly comment on the repo, file issues or make non-draft PRs without human review.

Code comments

  • Match the comment density of the surrounding code. Most lines need no comment.
  • Do not write comments that restate what the code does. Comment only on why, when the reason is not obvious from the code itself.
  • Comments describe the code as it is now. Never describe the previous behavior, the bug that prompted the change, or code that only existed in intermediate versions of your change (e.g. “now uses X instead of Y”, “fixed the off-by-one here”). That history belongs in the commit message or the PR description.

Where and how to make changes

dateutil.rrule

The goal with rrule is to be compliant with the iCalendar RFCs (2445, 5545 and the others in that lineage that have updated the RRULE and related data types). Please keep this in mind when evaluating bugs and potential changes to the API.

dateutil.tz

Most of what dateutil.tz does has now been supplanted by the zoneinfo module and datetime.timezone. If looking for something to do, better to focus on other modules, but changes and bugfixes are accepted here.

dateutil.parser

For the most part, dateutil.parser.parse is frozen. We may accept improvements which provably give identical behavior or improve the clearly specified contract of the function. Most of the function's behavior is very poorly specified, and so most parse changes will not be accepted.

dateutil.parser.isoparse has a much better-specified contract, so changes to it do not have the same restrictions.

Other modules

There are no special instructions for other modules.

Running the tests

Run tests with tox and in isolated environments if possible.