# Document LDM latex documentation development process

XMLWordPrintable

## Details

• Type: Story
• Status: Done
• Resolution: Done
• Fix Version/s: None
• Component/s:
• Labels:
None
• 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.

## Activity

Tim Jenness created issue -
Hide
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
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?
Field Original Value New Value
Reviewers John Swinbank, Jonathan Sick, Kian-Tat Lim [ swinbank, jsick, ktl ]
Status To Do [ 10001 ] In Review [ 10004 ]
 Watchers John Swinbank, Jonathan Sick, Kian-Tat Lim, Tim Jenness [ John Swinbank, Jonathan Sick, Kian-Tat Lim, Tim Jenness ] John Swinbank, Jonathan Sick, Kian-Tat Lim, Tim Jenness, Wil O'Mullane [ John Swinbank, Jonathan Sick, Kian-Tat Lim, Tim Jenness, Wil O'Mullane ]
Hide
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
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
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
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
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
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
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
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).
 Link This issue relates to DM-11952 [ DM-11952 ]
 Link This issue is triggering DM-11592 [ DM-11592 ]
 Link This issue is triggering DM-11592 [ DM-11592 ]
 Link This issue is triggering DM-11952 [ DM-11952 ]
Hide
Tim Jenness added a comment -

Work was completed in DM-11952.

Show
Tim Jenness added a comment - Work was completed in DM-11952 .
 Resolution Done [ 10000 ] Status In Review [ 10004 ] Done [ 10002 ]
 Link This issue relates to DM-11952 [ DM-11952 ]
 Comment [ [~jsick] did you use this ticket for finalizing the work on the developer guide or something else? I see that the developer guide has now been updated with the LDM writing guide so this ticket should be closed. ]
 Comment [ I see you used DM-11952. I'll close this ticket. ]

## People

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

## Dates

• Created:
Updated:
Resolved: