Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-6639

Developer guide incorrectly calls improvements "enhancements".

    Details

      Description

      By means of GitHub Pull Request, Gregory Dubois-Felsmann notes that https://developer.lsst.io/processes/workflow.html incorrectly refers to "enhancement" when it means "improvement". Please fix it.

        Attachments

          Activity

          swinbank John Swinbank created issue -
          swinbank John Swinbank made changes -
          Field Original Value New Value
          Issue Type Story [ 10001 ] Bug [ 1 ]
          swinbank John Swinbank made changes -
          Component/s Stack Documentation and UX [ 12880 ]
          Hide
          gpdf Gregory Dubois-Felsmann added a comment -

          The use of a PR without an associated ticket (and ticket branch) was an experiment that Jonathan Sick and I devised, trying to find the minimal-effort way for someone to post a comment on an LTD-based document. (In a mild irony, this arose in a discussion of our communication tools, including Confluence, and although we are in total agreement that Github/LTD is the way to go for software documentation, I was gazing with envy on the ease of making inline comments in Confluence.)

          The idea was that one could use Github's in-browser code editor and ::note directives to provide a way to place comments inline with document content (as is trivial in Confluence) while staying within the LTD workflow. The least-cost path here is to just click on the edit-pencil icon for the offending file to create the change and associated PR. That flow offers the option of entering a branch name. It would be possible to then go off, create the JIRA issue, then paste "branch/DM-nnnn" into the appropriate field, and create the PR, but that's a bit awkward and manual, and has a race condition where the issue appears before its associated content. Jonathan Sick is going to think about whether this could be more automated somehow. In the mean time, we thought we'd try just accepting the default branch name Github supplies.

          Out of curiosity, how did the PR come to your attention, John Swinbank?

          Show
          gpdf Gregory Dubois-Felsmann added a comment - The use of a PR without an associated ticket (and ticket branch) was an experiment that Jonathan Sick and I devised, trying to find the minimal-effort way for someone to post a comment on an LTD-based document. (In a mild irony, this arose in a discussion of our communication tools, including Confluence, and although we are in total agreement that Github/LTD is the way to go for software documentation, I was gazing with envy on the ease of making inline comments in Confluence.) The idea was that one could use Github's in-browser code editor and ::note directives to provide a way to place comments inline with document content (as is trivial in Confluence) while staying within the LTD workflow. The least-cost path here is to just click on the edit-pencil icon for the offending file to create the change and associated PR. That flow offers the option of entering a branch name. It would be possible to then go off, create the JIRA issue, then paste "branch/DM-nnnn" into the appropriate field, and create the PR, but that's a bit awkward and manual, and has a race condition where the issue appears before its associated content. Jonathan Sick is going to think about whether this could be more automated somehow. In the mean time, we thought we'd try just accepting the default branch name Github supplies. Out of curiosity, how did the PR come to your attention, John Swinbank ?
          Hide
          gpdf Gregory Dubois-Felsmann added a comment - - edited

          What would be really nice is if somehow one could hack Github to allow inline commenting on existing code as easily as on a PR or other commit. Then it might be natural to use that UI for the purposes of, say, creating a Github issue.

          As it is, without some sort of inline commenting, the barrier to people submitting small corrections/suggestions is much higher. If I have a number of comments on a document, and I want to do it in JIRA or in a Github issue, I have to write my comments in such a way that the references back to the document are at least unambiguous, even if they aren't actually useful in taking the reader straight to the code to be edited. For an LTD document the best way to do this probably would be to copy/paste in the permalinks to section headers provided by the HTML renderer (hover over a section title to see the permalink icon appear next to it).

          But this is an order of magnitude more trouble than the use of a natural inline commenting scheme.

          Of course, if the commenter is confident enough to actually edit the document, then a PR is the natural vehicle in any event - but even in that case it would be nice to ease the process of also generating a matching JIRA ticket to support the ticket-based workflow of merging the edits to master.

          (And if you are now wondering why I didn't just actually edit "enhancement" to "improvement" myself, the answer is that Jonathan Sick and I were deliberately using this as a test case for how to accept comments.)

          Show
          gpdf Gregory Dubois-Felsmann added a comment - - edited What would be really nice is if somehow one could hack Github to allow inline commenting on existing code as easily as on a PR or other commit. Then it might be natural to use that UI for the purposes of, say, creating a Github issue. As it is, without some sort of inline commenting, the barrier to people submitting small corrections/suggestions is much higher. If I have a number of comments on a document, and I want to do it in JIRA or in a Github issue, I have to write my comments in such a way that the references back to the document are at least unambiguous, even if they aren't actually useful in taking the reader straight to the code to be edited. For an LTD document the best way to do this probably would be to copy/paste in the permalinks to section headers provided by the HTML renderer (hover over a section title to see the permalink icon appear next to it). But this is an order of magnitude more trouble than the use of a natural inline commenting scheme. Of course, if the commenter is confident enough to actually edit the document, then a PR is the natural vehicle in any event - but even in that case it would be nice to ease the process of also generating a matching JIRA ticket to support the ticket-based workflow of merging the edits to master. (And if you are now wondering why I didn't just actually edit "enhancement" to "improvement" myself, the answer is that Jonathan Sick and I were deliberately using this as a test case for how to accept comments.)
          jsick Jonathan Sick made changes -
          Assignee Jonathan Sick [ jsick ]
          Hide
          swinbank John Swinbank added a comment -

          Out of curiosity, how did the PR come to your attention, John Swinbank?

          I keep an eye on GitHub – that's part of the T/CAM job description.

          For an LTD document the best way to do this probably would be to copy/paste in the permalinks to section headers provided by the HTML renderer

          When referring to code on GitHub from a JIRA ticket, I tend to create a link to a specific line of code in a specific commit (i.e. https://github.com/lsst-dm/dmtn-020/blob/813237e30a130aa117d958170118eab8e1cf8b98/conf.py#L28, not https://github.com/lsst-dm/dmtn-020/blob/master/conf.py#L28). That's certainly clunky.

          That said, while dealing with a moderately large number of comments on DMTN-020 (see e.g. DM-6447), I'd characterize this as gentle friction rather than a serious problem. Of course, it might be more of an issue for those less familiar with our JIRA/GitHub, particularly if they are coming from outside the project.

          Show
          swinbank John Swinbank added a comment - Out of curiosity, how did the PR come to your attention, John Swinbank? I keep an eye on GitHub – that's part of the T/CAM job description . For an LTD document the best way to do this probably would be to copy/paste in the permalinks to section headers provided by the HTML renderer When referring to code on GitHub from a JIRA ticket, I tend to create a link to a specific line of code in a specific commit (i.e. https://github.com/lsst-dm/dmtn-020/blob/813237e30a130aa117d958170118eab8e1cf8b98/conf.py#L28 , not https://github.com/lsst-dm/dmtn-020/blob/master/conf.py#L28 ). That's certainly clunky. That said, while dealing with a moderately large number of comments on DMTN-020 (see e.g. DM-6447 ), I'd characterize this as gentle friction rather than a serious problem. Of course, it might be more of an issue for those less familiar with our JIRA/GitHub, particularly if they are coming from outside the project.
          jsick Jonathan Sick made changes -
          Epic Link DM-6198 [ 24714 ]
          jsick Jonathan Sick made changes -
          Story Points 0.1
          Hide
          jsick Jonathan Sick added a comment -

          Self-merged.

          The discussion happening on this ticket can be continued on Community if needed.

          Show
          jsick Jonathan Sick added a comment - Self-merged. The discussion happening on this ticket can be continued on Community if needed.
          jsick Jonathan Sick made changes -
          Resolution Done [ 10000 ]
          Status To Do [ 10001 ] Done [ 10002 ]
          Hide
          swinbank John Swinbank added a comment - - edited

          Can we also close down this GitHub PR? I'm unclear whether you need that for ongoing discussion.

          Show
          swinbank John Swinbank added a comment - - edited Can we also close down this GitHub PR ? I'm unclear whether you need that for ongoing discussion.
          Hide
          gpdf Gregory Dubois-Felsmann added a comment - - edited

          Yes, you can close the PR. (As far as I am concerned.)

          Show
          gpdf Gregory Dubois-Felsmann added a comment - - edited Yes, you can close the PR. (As far as I am concerned.)

            People

            • Assignee:
              jsick Jonathan Sick
              Reporter:
              swinbank John Swinbank
              Watchers:
              Gregory Dubois-Felsmann, John Swinbank, Jonathan Sick
            • Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Summary Panel