Confusing wording in documentation

[RolfWojtech]

First of, thanks for writing this plugin.

I am considering to replace the patch from https://www.redmine.org/issues/14318 with this plugin. In Readme.md I stumbled upon a section that confused me a bit:

"This plug-in allows to unambiguously add a watcher to an issue if and only if this provides additional view permissions to the watcher user." When I read this strictly logically, this would mean that a user who already has permissions (e.g. by being creator or assignee) cannot be added as a watcher because the condition "if and only if this provides additional view permissions to the watcher user" is not met. Surely this is not the case (I have not tested it yet).

I think 4.2 changed the previous default behaviour that you were trying to describe with this sentence. Before 4.2, it was possible to select somebody as a watcher even if they would then not be able to view the issue. There were two possible "directions" to fix it in redmine itself: 1) Allow everyone to be added as a watcher and give them the proper permissions 2) Only allow users to be added as watchers who already have sufficient visibility Redmine went for Option 2.

I tried to come up with a solution for replacing the above sentence but didn't find a way to make it work. What are you trying to convey with it?

Finally, I would also be curious if you (maxrossello or anyone else here) were familiar with the patch and if this plugin offers comparable functionally as I understand it.

[maxrossello]

Agreed, the wording may confuse at the point that I had myself to reconstruct the meaning.

The meaning is the following: contrary to the default Redmine behavior, which allows to add a watcher without providing real access to an issue, this plugin ensures that if a user is a watcher, then s/he can also access to the issue. So, it is excluded that a user can be a watcher and not having access to the watched issue.

In extended mode, every user can be addes as a watcher because additional access permissions can be assigned by watching to everybody. In protected mode, only users that can already access the project can access to issues that they can't see by being assigned as watchers. This means that users that can't see the project can't gain additional permissions, but they can't be assigned as watchers either.

I agree with you that additional may be the confusing thing. If a user can access an issue, it can always be assigned as a watcher as well, and there's no additional permission involved. Would be removing additional more clear in your opinion?

Thanks for your feedback!

[maxrossello]

Finally, I would also be curious if you (maxrossello or anyone else here) were familiar with the patch and if this plugin offers comparable functionally as I understand it.

I took inspiration from some thread of discussion and some related patch proposal quite some time ago, but I don't think I ever met the patch that you mention. In my understanding that offers some additional bit of configuration, doesn't it?

[RolfWojtech]

Thanks for the quick reply.

I thought about fixing the sentence but after much contemplation, I spent entirely too much time crafting a new version of the introduction. It gets to the points a bit quicker and more accurately describes the different behaviours:

This Redmine plug-in allows you to add users as issue watchers even if they don't have sufficient viewing permissions (Extended Mode). The user will be "soft-granted" viewing permissions to the project and the watched issue.
Alternatively, it allows you to prevent adding watchers that do not have sufficient viewing permissions already (Protected Mode).

For context:
In earlier versions of Redmine (<4.2), non member users of a project could be added as issue watchers by member users without gaining the necessary view permission to see the project and the issue itself.
This plug-in was originally created to fix this misleading behaviour in one of two chooseable directions: either forbid such users as Watchers or allow them but simultaniously soft-grant them the needed permissions.
Starting with Redmine 4.2, the default behaviour was made more consistent by not allowing such users as Watchers, compareable to the Protected Mode of this plug-in.
In summary, this plug-in you can "backport" the protective behaviour of 4.2 to earlier versions of Redmine or allow you to be more permissive via Extended Mode in any Redmine version.

Refer to the Configuration paragraph below for further details.

I was also wondering if the protected mode even makes sense in Redmine 4.2. Without having tested it, it reads like it is identical to the default behaviour of 4.2 since this patch was accepted into mainline: https://www.redmine.org/issues/33329

Personally I think the new 4.2 behaviour shows that the redmine team has at least half-understood the issue. Since this plug-in offers a very sensible usability improvement, it might make sense to try to get it into future redmine versions.

[maxrossello]

Thanks a lot!

Yes, I feel that the protected mode is still useful because it allows to create an e.g. Watcher role and, through that, configure more issues permissions to assign to the otherwise unprivileged member when assigned as a watcher. Please have a look at https://github.com/maxrossello/redmine_extended_watchers/issues/31

[maxrossello]

Please have a look to the new wording on the master branch, if it looks ok to you. Thanks!

[RolfWojtech]

Looks great, much easier to understand now. Also thanks for explaining the benefits of protected mode in 4.2, that was also very understandable from the main page now. I'm closing here and am excited to try this plug-in out soon.