wishlist for 4.0 :-)

[studioj]

drop those things in here.

bumping a major version means changes which might break the API

I'll start with it

• i'd like to make sure method names are more pythonic and in version 4.0 raise deprecation warnings for the camelcase methods

[adehad]

I'd quite like to move away from passing strings into arguments when an object could be passed instead. e.g.

    @translate_resource_args
    def add_watcher(self, issue: str, watcher: str) -> Response:
        """Add a user to an issue's watchers list.

        Args:
            issue (str): ID or key of the issue affected
            watcher (str): name of the user to add to the watchers list
        """
        url = self._get_url("issue/" + str(issue) + "/watchers")
        return self._session.post(url, data=json.dumps(watcher))

Would become

    @translate_resource_args
    def add_watcher(self, issue: Issue, watcher: User) -> Response:
        """Add a user to an issue's watchers list.

        Args:
            issue (Issue): Issue affected
            watcher (User): user to add to the watchers list
        """
        url = self._get_url(f"issue/{issue.key}/watchers")
        return self._session.post(url, data=json.dumps(watcher.accountId if self.deploymentType == "Cloud" else watcher.name))

Would be a pretty big change from a user perspective, but I feel like this will make things more robust long term for both sides.

The user workflow may change from:
providing the email/username/accountId to the function
to:
searching for the user using the email/username, then passing the resulting User object into the function

We could provide some helper methods that may make this less painful:

jira_client : JIRA
jira_client.add_watcher(issue=get_issue(key="PRJ-123"), watcher=get_user(email="[email protected]"))

[studioj]

well as an intermediate deprecation step we could support both
key and Issue => raising a deprecation warning when "key" is provided

[misterashley]

Personally speaking, I may not have been able to engage with this software if it was more object-y. Objects make using code harder, or at least a higher barrier for the uninitiated. Objects are a more complex level of abstraction that I find challenging. (I didn't go to school for this.)

Strings, on the other hand, are super easy to understand: they're text.

I have a working application using functional programming that I am so delighted to be able to use. It makes my work faster and more accurate. I'm grateful for this project allowing me to build such a tool.

For me, and many, it's super easy to pass a string. I frequently play around with your code to experiment with possibilities.

For example, I know I can create an issue object by doing something like:
issue = jira.issue('<some ticket>')
and then I play around in the shell to try to figure out what it can do.

However if I couldn't pass a string to create the object which then I could experiment with, my worry is that it would have cut me off from being able to use this project at all.

Just my two cents. Thanks for the opportunity to respond.

[studioj]

@misterashley, thank you for your insights
we should try to keep in mind not all users are super proficient software developers

[studioj]

making a better segregation between jira server and jira cloud

[petermcd]

Curious, in what way segregated?

Should it matter to an end user as to wether they are using cloud, data center or server on how they would use the package?

[studioj]

no by far not :) but to be able to more easily remove the support for jira server once it gets out of service (planned 2026)

[petermcd]

Not something that is functionally relevant but while looking through the package it would help if things like the comments were in a consistant manner, In client.py for example the 3 following styles are used (as well as some functions not commented at all)

        """Get a list of comment Resources.

        :param issue: the issue to get comments from
        :type issue: str
        :param expand: extra information to fetch for each comment
                       such as renderedBody and properties.
        :type expand: str
        :rtype: List[Comment]
        """

        """Internal method for translating an user search (str) to an id.

        Return None and -1 unchanged.

        This function uses :py:meth:`JIRA.search_users` to find the user
        and then using :py:meth:`JIRA._get_user_identifier` extracts
        the relevant identifier property depending on whether
        the instance is a Cloud or self-hosted Instance.


        Args:
            user (Optional[str]): The search term used for finding a user.
              None, '-1' and -1 are equivalent to 'Unassigned'.

        Raises:
            JIRAError: If any error occurs.

        Returns:
            Optional[str]: The Jira user's identifier. Or "-1" and None unchanged.
        """

"""Decorator that converts Issue and Project resources to their keys when used as arguments."""

Each of the above are for functions/generators that take arguments and have a return value.

Typing seems to be missing in places (or at least is not obvious). Improving typing may help.

Guessing this would come down to a general code clean up in general.

[studioj]

@petermcd
#1396 open for review

[petermcd]

I think it would be great for Insight access, this is something that I am looking at implementing if it is a possibility (discussion in a currently open issue I created)

[LucasCallista]

Some general file structure would be great the main file client.py is enormous
perhaps move more functions to the resources and away from the jira client and split the resources.py file in a file per resource

[studioj]

I think we should also rethink the way we are testing things. It's hard for people to add tests, its hard to run them.

[studioj]

another feature proposal => historical issues
for example give me the issue at day x (for example you 'd like to know how the story points of a story changed over time or the assignee or other things)

[harshadapshankar]

It would be nice to have some helper function to get custom field names and their possible values. I can get custom fields printed and it prints something like this:
{'id': 'customfield_16271', 'name': 'Sizing Confidence', 'custom': True, 'orderable': True, 'navigable': True, 'searchable': True, 'clauseNames': ['cf[16271]', 'Sizing Confidence'], 'schema': {'type': 'option', 'custom': 'com.atlassian.jira.plugin.system.customfieldtypes:select', 'customId': 16271}}

But I have no way to get ids of all possible values that can be assigned to this custom field 'customfield_16271' (i.e. options in the select box) programmatically.