Skip to content

Changelog

v0.16.1 - 2026-09-14

Fixed

  • Create-metadata helpers now aggregate official Jira REST API v3 issueTypes and fields pages using startAt and the current page's total. issue_types() preserves Jira's ordered bare raw list, while create_fields() stops issue-type discovery at the first case-insensitive match with a nonblank raw ID and aggregates all field pages. Later failures raise JiraHelperOperationError rather than returning partial lists.
  • Tightened undocumented test/mock compatibility: metadata-free pages and values/isLast-only create-metadata pages are no longer accepted by the high-level helpers. Low-level create-metadata methods remain unchanged one-page raw pass-throughs.

v0.16.0 - 2026-09-11

Breaking changes

  • Attachments.download_attachment_content() no longer returns buffered bytes. It now requires a binary destination and positive max_bytes, streams bounded content, and returns observed bytes. Optional expected_size enforces an exact count.
  • Removed AttachmentDownloadPlan and AttachmentHelpers.plan_download(). Use AttachmentHelpers.download(attachment_id, *, directory=".", filename=None, max_download=...), which owns metadata lookup, filename handling, temporary files, and atomic replacement. Result data now reports observed size and no longer exposes content_url.

Security and reliability

  • Public attachment transfers start at the configured Jira endpoint, follow redirects without forwarding credentials cross-origin, enforce limits cumulatively, retry 429 only before output starts, and report sanitized failures. Missing metadata size uses only the cap; supplied zero requires an empty transfer. The separate managed-media bounded reader is unchanged.

v0.15.0 - 2026-09-09

Added

  • Managed Jira Markdown images now receive exact intrinsic dimensions before a helper writes ADF. A 64-byte authenticated no-follow range probe handles PNG/APNG, GIF, WebP, and BMP first; JPEG, TIFF, and inconclusive probes use one complete fallback limited to 100 MiB. JPEG/TIFF EXIF orientation is applied. Dimensions must be positive, at most 65,535 per axis, and at most 89,478,485 pixels. The resulting managed media is centered at 100% parent width with intrinsic child dimensions.

Compatibility

  • Public attachment downloads retain their existing redirect-following, fully buffered behavior. Managed-image acquisition remains private, avoids external fetches, and verifies raw persisted ADF structure rather than making a browser-rendering claim.

Security fixes

  • Private managed-image reads use redirect=false, do not follow redirects, request identity encoding, and validate the response status, byte range, total size, and length before parsing in-memory bytes. Malformed, oversized, incomplete, or redirected responses are rejected; attachment bytes are not persisted.

v0.14.0 - 2026-09-07

Added

  • Replaced direct marklassian and pyadf use with adf-bridge>=0.1.2. Formatted ADF presentation uses adf-bridge's identity-preserving [~accountId:<id>] mention tokens and remains readable and presentation-only; managed media attachment-content URLs cannot be recovered from formatted Markdown or leak Media Services IDs.
  • Added automatic Jira-managed Markdown images on existing-issue high-level writes: issue edit rich fields, comment add/update, and worklog add/update. Only canonical configured-Jira attachment-content URLs for associated image/* attachments qualify; source query and fragment delimiters, including bare ? and #, are rejected. Create remains create → upload → complete-field edit, never an implicit upload. Jira's private no-follow 303 Media Services mapping is compatibility-sensitive observed behavior; public bytes downloads remain unchanged. Verification reads raw persisted ADF structure, not rendered response expansions.
  • Direct issue, comment, and worklog mutations now flag connection and Jira 5xx failures as potentially delivered with mutation_may_have_succeeded; callers must reread before retrying, and jira2py does not retry or roll back after that uncertain failure.

v0.13.0 - 2026-09-04

Breaking changes

  • High-level Markdown inputs shaped as [~accountId:<id>] now create Jira mentions rather than literal text.

Added

  • Added universal Jira account mentions to high-level Markdown writes: issue create/edit descriptions, environment, compatible custom textarea fields, comment add/update bodies, and worklog add/update comments. Input accepts case-insensitive accountId, including IDs containing :. Formatted ADF reads remain presentation-only through pyadf and can lose mention identity if edited and written back; raw ADF is required for identity-safe edits until dedicated formatted read/edit/write support is added.

v0.12.0 - 2026-09-01

Added

  • Added named low-level transition-discovery controls for includeUnavailableTransitions, skipRemoteOnlyCondition, and sortByOpsBarAndStatus, while retaining the existing positional arguments and extra_params precedence.
  • Added focused transition discovery through MetadataHelpers.transitions(..., transition_id=..., include_unavailable_transitions=...). It always expands transitions.fields, keeps Jira's complete raw transition envelope in helper data, and presents destination IDs/names, availability and workflow indicators, plus screen field keys/names/requirements/operations.
  • Added Jira-native fields and update mappings to IssueHelpers.transition(). The helper rejects exact overlap between their field keys, forwards neither submitted body in its result, and leaves Jira as the validator for screen requirements and field values. Successful helper transition results now add verified: false: Jira accepted the request, but jira2py did not perform a verification read and reports the destination only as expected.

v0.11.0 - 2026-08-28

Added

  • Added one-page IssueFields.search_fields() support for Jira's stable /field/search endpoint, including canonical field IDs, system/custom type filters, project IDs, ordering, expansions, and raw query overrides. IssueFields.get_fields() is unchanged.
  • Added MetadataHelpers.list_fields() for one searchable raw field page with concise canonical-ID text and optional project-key-to-numeric-ID context resolution. Jira documents field search for Classic projects; project context does not determine issue-type or create/edit-screen applicability.
  • Added exact case-sensitive raw fieldId filtering to ordinary and known-ID changelog helpers. Ordinary changelog retrieval also supports optional post-filter event pagination with result_page metadata after all Jira pages, timestamp filtering, item pruning, and empty-event removal.

v0.10.0 - 2026-08-27

Added

  • Added Issues.get_changelogs_by_ids() for Jira's official issue-scoped changelog-list POST endpoint.
  • Added JiraHelpers.changelogs for complete changelog retrieval with optional UTC-normalized half-open creation bounds, plus one-request known-ID retrieval.
  • Added permissive changelog/page models and concise changelog helper text while retaining complete original Jira mappings in structured helper output.

v0.9.0 - 2026-08-23

Breaking changes

  • Issues.get_issue() now accepts Sequence[str] | None for fields. A supplied sequence is validated and serialized only at the Get Issue endpoint; comma-delimited scalar strings are no longer accepted.
  • Removed IssueHelpers.read() and its fixed retrieval profile. Retrieve issues directly with JiraAPI, which now remains the sole full-issue retrieval authority.
  • fields=None omits the parameter for Jira's default behavior unless raw extra_params["fields"] overrides it. Selectors are forwarded exactly, without implicit fields or expand; wildcard and negative selectors may be broad.
# Before (removed)
from jira2py.helpers import JiraHelpers

helpers = JiraHelpers(api)
api.issues.get_issue("PROJ-123", fields="summary,status")
helpers.issues.read("PROJ-123", extra_fields=["customfield_10001"])

# After
from jira2py.helpers import format_issue

issue = api.issues.get_issue(
    "PROJ-123",
    fields=["summary", "status", "customfield_10001"],
)
text = format_issue(
    issue,
    browse_url=f"{api.credentials.url}/browse/{issue['key']}",
)

Added

  • Added public pure jira2py.helpers.format_issue(data, *, browse_url=None) for optional presence-aware issue text presentation without I/O, mutation, or retrieval policy.

v0.8.1 - 2026-08-22

Fixed

  • Fixed cursor continuation for enhanced search and saved-filter runs by accepting next_page_token in SearchHelpers.issues() and FiltersHelpers.run() and forwarding it to IssueSearch.enhanced_search(). Each call returns one raw Jira page; callers must pass the returned nextPageToken to request the next page.

v0.8.0 - 2026-06-28

Added

  • Added opt-in complete JSON credential files through credentials_file, with explicit constructor values taking precedence over file values and environment variables. No default credential-file path is used.
  • Expanded Jira Cloud operation coverage with current-user/auth status, issue transitions, comment update/delete, attachment list/metadata/download/upload/delete, issue-link listing, project lookup, status and priority metadata, and saved-filter list/search/run operations.
  • Added low-level worklog add/update/delete operations and high-level worklog list/add/update/delete workflows on the paginated retrieval API introduced in v0.6.0.
  • Added agent-readable authentication failures and explicit attachment upload/delete result contracts.

v0.7.0 - 2026-06-25

Added

  • Added jira2py.helpers.JiraHelpers, a grouped high-level workflow facade around the unchanged low-level JiraAPI.
  • Added grouped helper entry points for issues, search, comments, worklogs, attachments, metadata, and links.
  • Added HelperResult and helper-layer errors for readable workflow output plus structured data.
  • Added validation that rejects supplying an issue description both through IssueHelpers.create(description=...) and through its fields mapping, avoiding an ambiguous create payload.

Documentation

  • Documented when to use low-level JiraAPI vs high-level JiraHelpers.
  • Added high-level helper guide/API reference pages and a repository example.
  • Documented that private helper internals such as jira2py.helpers._adf and jira2py.helpers._text are internal implementation details, not supported public API.

v0.6.0 - 2026-06-25

Added

  • Added the low-level IssueWorklogs API at JiraAPI.worklogs for paginated issue-worklog retrieval.

v0.5.0 - 2026-06-23

Compatibility-honest minor release for accepted caller-visible behavior changes that should not be framed as a patch-only update.

Compatibility notes

  • extra_params and extra_data override named query/body fields when the same keys are provided in both places.
  • JiraAuthenticationError subclasses JiraAPIError, so broad except JiraAPIError handlers also catch authentication/authorization failures.
  • search.enhanced_search() omits optional None values from the request body instead of sending JSON null.

Documentation

  • Clarified the caller-visible precedence behavior for extra_params and extra_data.
  • Documented the JiraAuthenticationError / JiraAPIError hierarchy and shared API error metadata (status_code, response, and error_messages) when available.
  • Documented that search.enhanced_search() omits optional None values from the request body.

Tooling

  • Added a reusable version bump helper plus safer release-prep and tag-push automation for the dev -> PR -> main -> tag release flow.

v0.4.0

Breaking Changes

  • New entry point — The library is now accessed through a single JiraAPI facade. The previous per-class imports (from jira2py import Issues) have been removed. See Installation for the new usage.

  • Constructor parameter names changed:

    v0.3.x v0.4.0
    jira_url url
    jira_user username
    jira_api_token api_token

  • raw_response mode removed — All methods return parsed JSON (dict, list, or None).

  • Method signature changes — Several methods had parameters removed in favor of extra_params / extra_data. See API Reference — Conventions for how to pass additional parameters.

    • get_issue() — removed: fields_by_keys, properties, update_history, fail_fast
    • edit_issue() — removed: override_screen_security, override_editable_flag, history_metadata, properties, transitions, update, additional_properties
    • enhanced_search() — removed: properties, fields_by_keys, fail_fast, reconcile_issues

  • Return type changes:

    • edit_issue() returns None on success instead of True. Returns dict when return_issue=True.
    • get_changelogs() returns the full paginated response dict instead of just the values list.

  • Error types changed — All errors were previously raised as ValueError. They are now specific exception types. See Error Handling.

  • Pydantic validation removed — @validate_call decorators are no longer used. Type hints remain for IDE support and static analysis.

New Features

  • Unified API facade — Single JiraAPI entry point with access to all modules via properties (jira.issues, jira.search, jira.comments, etc.).

  • Automatic rate limit handling — Requests that receive HTTP 429 are retried automatically with exponential backoff and Retry-After header support. See Rate Limiting.

  • Structured exception hierarchy — Typed exceptions for authentication errors, not found, validation failures, rate limits, and connection issues. See Error Handling.

  • 11 new API methods:

    Method Description
    issues.create_issue() Create a new issue
    issues.get_edit_metadata() Get fields available for editing
    issues.get_create_issue_types() Get issue types for a project
    issues.get_create_fields() Get fields for creating an issue type
    comments.add_comment() Add a comment to an issue
    issue_links.get_link_types() List available link types
    issue_links.create_link() Link two issues
    issue_links.delete_link() Delete an issue link
    attachments.get_attachment_metadata() Get attachment metadata
    projects.search_projects() Search and list projects
    users.search_users() Search users by name or email

  • HTTP/2 support with persistent connections and configurable timeouts.

  • PEP 561 compliant — py.typed marker included for downstream type checking.

Bug Fixes

  • get_comments() ordering — Fixed the order_by query parameter name from orderby to orderBy. The incorrect name was silently ignored by Jira, so comments were always returned in default order.

Documentation

  • Migrated from Sphinx to MkDocs Material — complete rewrite of all documentation with new content, Material theme (light/dark toggle, navigation tabs, search, code copy, content tabs).

  • Machine-readable documentation for AI agents:

  • Documentation dependency changes:

    Removed Added
    sphinx mkdocs-material
    pydata-sphinx-theme mkdocs
    sphinx-sitemap mkdocs-llmstxt
    griffe

Dependency Changes

Removed Added
requests httpx[http2]
pydantic tenacity
pydantic-core
email-validator
python-dotenv

v0.3.1

Initial public release.