Describe identifiers more clearly in help and documentation #128
Conversation
There was a problem hiding this comment.
Thanks for the pull request and thanks for being involved in the Jenkins project.
I think that the guidance from @jtnord was that the acronym "ID" would be better expressed as the word "identifier" since it could be confused with many different forms of "ID". The page linked by @daniel-beck shows many possible expansions of the acronym "ID".
I don't have a strong objection to the existing changes in this pull request, though I think the changes that I've proposed will better address the concerns expressed by @jtnord and the questions raised by @daniel-beck .
There is a reference to Custom ID that is not covered in this pull request. I would not block the merge of this pull request based on that remaining reference, but I think it would be nice if this pull request or a future pull request also changed that reference. The picture I took looks like this:
Again, this pull request is already a step forward. I'm fine if it is merged as is or if it is merged with the changes that I suggested.
README.md
Outdated
| @@ -23,14 +23,14 @@ Input Example with `OK Button Caption`(Optional): | |||
| input message: 'input-message', ok: 'OK' | |||
|
|
|||
| Input Example with `Allowed Submitter`: | |||
| User IDs and/or external group names of person or people permitted to respond to the input, separated by ','. Spaces will be trimmed automatically, so "Alice, Bob, Charles" is the same as "Alice,Bob,Charles". | |||
| User ids and/or external group names of person or people permitted to respond to the input, separated by ','. Spaces will be trimmed automatically, so "Alice, Bob, Charles" is the same as "Alice,Bob,Charles". | |||
There was a problem hiding this comment.
In this case, I think that many places in the Jenkins documentation and changelogs use the word "username" to refere to the identifier of a user.
| User ids and/or external group names of person or people permitted to respond to the input, separated by ','. Spaces will be trimmed automatically, so "Alice, Bob, Charles" is the same as "Alice,Bob,Charles". | |
| Usernames and/or external group names of those permitted to respond to the input, separated by ','. Spaces will be trimmed automatically, so "Alice, Bob, Charles" is the same as "Alice,Bob,Charles". |
| @@ -1,6 +1,6 @@ | |||
| <p> | |||
| Every <code>input</code> step has an unique ID. It is used in the generated URL to proceed or abort. | |||
| Every <code>input</code> step has an unique id. It is used in the generated URL to proceed or abort. | |||
There was a problem hiding this comment.
| Every <code>input</code> step has an unique id. It is used in the generated URL to proceed or abort. | |
| Every <code>input</code> step has an unique identifier. It is used in the generated URL to proceed or abort. |
src/main/resources/org/jenkinsci/plugins/workflow/support/steps/input/InputStep/help-id.html
Outdated
Show resolved
Hide resolved
|
You may also want to rephrase the title of the pull request. Maybe consider: Describe identifiers more clearly in help and documentation |
Bharath-Ganesh
changed the title
Bharath-Ganesh
force-pushed
the
bhganesh/jenkinsci/refactor_ID_to_id
branch
from
913a8fe
to
e9d32e1
Compare
|
Thanks @MarkEWaite . Do I need to do anything else to get this merged? |
Not as far as I can tell. It will need to wait for a maintainer to review, approve, and merge it. |
The documentation for the input step used ID when taking about the id field.
I have refactored all the references of ID to id
LINK: https://issues.jenkins.io/browse/JENKINS-69889