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

Document LDM latex documentation development process

    Details

    • Story Points:
      4
    • Team:
      Architecture

      Description

      We are now developing DM change-controlled documents using latex but we have no documented policy for this or a description of the process. The process is slightly different to code development and involves specific requirements for review and release.

      Add a section to the developer guide.

        Attachments

          Issue Links

            Activity

            Hide
            tjenness Tim Jenness added a comment -

            I've made a first attempt at documenting LDM process. Can you please have a look and tell me what you need changed?

            Show
            tjenness Tim Jenness added a comment - I've made a first attempt at documenting LDM process. Can you please have a look and tell me what you need changed?
            Hide
            tjenness Tim Jenness added a comment -

            John Swinbank thank you for your review. I'm not attached to that process and I'm happy to talk about it. The constraints I have are:

            • How does .lsst.io web site know which version it is meant to show by default? Looking for tags on release branches to try to guess seems more flaky than "most recent tag on master".
            • If master is for "next version", how do we deal with a hotfix to the baselined document if some other major rewrite is ongoing? What if there are two rewrites ongoing? (as has almost happened with DPDD)?

            Of course, we could treat this as a test case for how we would handle code releases in general if we have to keep an old release branch active whilst developing new code for the next release. If we adopted that policy for these change-controlled documents then that would be a win (and we still have to solve the "latest official release" problem for .lsst.io). I've copied Wil O'Mullane in and I'm sure Frossie Economou will have thoughts on this.

            One option is to stick with the status quo of "master is baseline" until the release manager turns up.

            Show
            tjenness Tim Jenness added a comment - John Swinbank thank you for your review. I'm not attached to that process and I'm happy to talk about it. The constraints I have are: How does .lsst.io web site know which version it is meant to show by default? Looking for tags on release branches to try to guess seems more flaky than "most recent tag on master". If master is for "next version", how do we deal with a hotfix to the baselined document if some other major rewrite is ongoing? What if there are two rewrites ongoing? (as has almost happened with DPDD)? Of course, we could treat this as a test case for how we would handle code releases in general if we have to keep an old release branch active whilst developing new code for the next release. If we adopted that policy for these change-controlled documents then that would be a win (and we still have to solve the "latest official release" problem for .lsst.io). I've copied Wil O'Mullane in and I'm sure Frossie Economou will have thoughts on this. One option is to stick with the status quo of "master is baseline" until the release manager turns up.
            Hide
            jsick Jonathan Sick added a comment -

            I've started commenting on the document and started to summarize an alternative workflow at https://github.com/lsst-dm/dm_dev_guide/pull/156#pullrequestreview-63425668 and I see the same idea has already been discussed here so perhaps my discussion hasn't added anything meaningful to the conversation.

            I will say that I've very willing to implement code in LSST the Docs to make a `master` as draft workflow usable.

            Show
            jsick Jonathan Sick added a comment - I've started commenting on the document and started to summarize an alternative workflow at https://github.com/lsst-dm/dm_dev_guide/pull/156#pullrequestreview-63425668 and I see the same idea has already been discussed here so perhaps my discussion hasn't added anything meaningful to the conversation. I will say that I've very willing to implement code in LSST the Docs to make a `master` as draft workflow usable.
            Hide
            jsick Jonathan Sick added a comment -

            I think the next step is to make a decision on whether we want this ticket to document the current patterns, or establish the way we want things to work. If it's the latter I can focus my review on the current manuscript and we can move this forward quickly.

            Show
            jsick Jonathan Sick added a comment - I think the next step is to make a decision on whether we want this ticket to document the current patterns, or establish the way we want things to work. If it's the latter I can focus my review on the current manuscript and we can move this forward quickly.
            Hide
            tjenness Tim Jenness added a comment -

            I'd be inclined to document how we have been doing things (the current status) on this ticket and then discuss how to fix it for a future ticket. I don't want to delay mentioning LDMs in the guide until we work out the plan and that plan is implemented (eg having lsst.io query docushare for the most recent preferred version and linking that to the tagged version in the repo).

            Show
            tjenness Tim Jenness added a comment - I'd be inclined to document how we have been doing things (the current status) on this ticket and then discuss how to fix it for a future ticket. I don't want to delay mentioning LDMs in the guide until we work out the plan and that plan is implemented (eg having lsst.io query docushare for the most recent preferred version and linking that to the tagged version in the repo).
            Hide
            tjenness Tim Jenness added a comment -

            Work was completed in DM-11952.

            Show
            tjenness Tim Jenness added a comment - Work was completed in DM-11952 .

              People

              • Assignee:
                tjenness Tim Jenness
                Reporter:
                tjenness Tim Jenness
                Reviewers:
                John Swinbank, Jonathan Sick, Kian-Tat Lim
                Watchers:
                John Swinbank, Jonathan Sick, Kian-Tat Lim, Tim Jenness, Wil O'Mullane
              • Votes:
                0 Vote for this issue
                Watchers:
                5 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Summary Panel