fixes 320 - assignment when similar users exist

[michalporeba]

Description

Adds -Exact parameter to the Get-JiraUser which internally switches from using search to get user.
It is then used in the Set-JiraIssue when the -Assignee is set.

Motivation and Context

closes #320
closes #49
is continued by #306
Assigning users failing when Get-JiraUser for a specific username returns more than one user

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• My code follows the code style of this project.
• I have added Pester Tests that describe what my changes should do.
• I have updated the documentation accordingly.

[michalporeba]

I have a unit test to cover the -Exact option and modified one to be more explicit how the Get-JiraUser should work when the -Exact is not used. I have also updated the Get-JiraUser documentations.

[stevenyoungs]

Hi @michalporeba
I believe there are many places where Get-JiraUser is called, internally, and each would need to be investigated and potentially suffixed with the new -Exact switch. Additionally, any external call to Get-JiraUser would need to be evaluated and potentially suffixed with -Exact.
The approach I took with #306 was to modify the default behaviour of Get-JiraUser so that it does what your -Exact switch does. The upside as I see it is that, for the most common case of finding an exact user, no further source modifications are required; it 'just works!' As mentioned elsewhere, it is a breaking change and @lipkau, understandably, wants to wait for the next major release.
Much as I would personally love to see this problem fixed sooner, I don't disagree with the decision to await the next major release.

@lipkau do you have a schedule in mind for releasing 3.0?

[michalporeba]

As far as I see the failing tests are to do with documentation, I would need some guidence there to make it work, but let's talk about the two solutions.

Your change @stevenyoungs fixes much more than what I'm trying to achieve. The filter appears to be good long term solution, but it is a breaking change. Not only internally, but in any script people might have written using it.

My approach has only two things in mind. Fix the problem with assigning users and make sure the impact is minimal. The -Exact switch has the default value of $false and when it is false, there are no changes to the behaviour of JiraPS. The behaviour changes only when the switch is set to $true, and that is used only in one place in Set-JiraIssue. That makes the change very localised and easy to test. While it doesn't resolve much bigger problem, it solves one specific bug and could be successfully used in the current bersion before 3.0 is ready. Also, because it is a fix to that specific issue and not a replacement for your solution to the bigger problem I don't see why the -Exact would have to be added to the other commands.

[lipkau]

regarding the test failures:

• you must add a new parameter in the documentation: JiraPS/docs/en-US/commands/Get-JiraUser.md. I would recommend bellow https://github.com/AtlassianPS/JiraPS/blob/master/docs/en-US/commands/Get-JiraUser.md#-includeinactive

[lipkau]

@stevenyoungs : I don't think this PR is the ideal solution for this matter.
but as it has been raised a lot of times (and is a very old issue), I would allow this change to pass and refactor it with #306 for the next major version. hope you agree

[michalporeba]

Thanks for the information and review. I will make the changes tomorrow morning.

[michalporeba]

Thank you @lipkau for solving the documentation problem for me. Can you explain what it was? Was it just the missing ### -Exact above the yml section I have added? Is the parameter type difference important? I have seen in other places SwitchParameter used and you changed it to Switch.

[lipkau]

### is markdown for <h3/>.
So the name of the parameter must be the header for the description and yaml table.

you can see how that looks like in html on the documentation page:
https://atlassianps.org/docs/JiraPS/commands/Get-JiraUser/#parameters