Bug 1043742

Description of problem:

When you snapshot freeze a content spec, there is a whole other workflow you need to do to keep using that book as the latest version on docbuilder. Books no longer refresh automatically (because the spec is rev locked to a particular topic version).

Each time you want to update the Docbuilder published version you need to execute csprocessor snapshot 16459 --latest then push that version up to CCMS to refresh the build.


==Workflows==

Option 1: Use an SVN Branching Approach.

Your main content spec for each book is like /trunk, and each release you run a command that creates a /branch which is what you publish from.

1. Finish Docs Development
2. Run csprocessor snapshot --new <cs_ID> for the book (branch)
3. Publish using the ID of the "New" CS map.
4. Make note of the CS Map ID and add to a document in project docs.
5. Continue development in the "original" for the next release.

NOTE: --new means that an entirely new content spec is created with none of the previous release's metadata. The metadata is all stored in the /trunk version.

NOTE: If you are using a Revision History topic, you will need to clone this as well and update that in the --new spec.

Option 2: Clone spec and continue development on the cloned spec as /master

1. Finish Docs Development
2. Clone the CSP map in the CCMS interface.
3. Clone the Revision History topic.
4. Update the Revision History topic ID in the cloned spec. 
5. Freeze the original CSP map.
6. Continue development on the cloned map.




Additional info:

IRC log that sparked this docs bug:

(01:22:42 PM) lnewson: jmorgan, the content spec is "frozen" and isn't pointing to the new changes you made in the topic
(01:22:53 PM) lnewson: ie on line 62:       Understanding import-resource Operation [16548, rev: 471407]
(01:23:17 PM) lnewson: but the changes you made are in revision 569840 of topic 16548
(01:23:30 PM) jmorgan: Yeah, thats the problem I think lnewson
(01:23:45 PM) jmorgan: So how do I bump the spec correctly. 
(01:23:58 PM) ***jmorgan should probably read the user guide I"m currently updating...
(01:24:38 PM) lnewson: I don't think there's any info on that tbh, as I thought I saw an RFE in the bug queue
(01:24:52 PM) jmorgan: OK.
(01:25:00 PM) rdickens: OK, sorry. i thought the issue was with the latest build of the book not being reflected on docbuilder
(01:25:07 PM) lnewson: anyways, it gets a bit tricky there. Assuming you want all the latest content you could do something like:
(01:25:34 PM) lnewson: csprocessor pull-snapshot 16459 --latest
(01:25:45 PM) adahms-lunch is now known as adahms
(01:25:46 PM) lnewson: and then push that back up over the existing one
(01:26:24 PM) lnewson: but if you only want to select some topics then I'm affraid you'd have to do it manually
(01:26:38 PM) jmorgan: So lnewson, once you freeze a content spec, that is the version that displays in perpetuity until you intervene on teh command line.
(01:26:47 PM) lnewson: yep
(01:27:02 PM) jmorgan: OK, there should be some docs around that I think.
(01:27:21 PM) smumford_afk is now known as smumford
(01:27:40 PM) rdickens: lnewson: as you have said, you can also bump specific topic's revisions to include updated content
(01:27:59 PM) rdickens: in fact that's what we are having to do on all EAP content as of now  :O
(01:28:12 PM) jmorgan: So the work-around after freezing your specs for say 6.1 and starting on 6.2 dev, would be:
(01:28:12 PM) jmorgan: 1. csprocessor pull-snapshot 16459 --latest
(01:28:12 PM) jmorgan: 2. csprocessor push 16459
(01:28:47 PM) lnewson: yeah, when talking to Tom we did come up with a way to select the what content specs should be updated as well but we haven't looked into it anymore yet
(01:28:59 PM) lnewson: jmorgan, not quite (I skipped a little sorry)
(01:29:05 PM) rdickens: lnewson: why not do a "csprocessor snapshot <content-spec-ID>" ?
(01:29:23 PM) lnewson: actually good idea rdickens 
(01:29:29 PM) jmorgan: lnewson: No problems.
(01:29:43 PM) lnewson: jmorgan, if you just run "csprocessor snapshot 16459 --latest" that should fix it
(01:29:54 PM) lnewson: thanks rdickens, I'd forgotten about that
(01:30:08 PM) jmorgan: OK. So you snapshot the spec, then push it back up again, correct?
(01:30:12 PM) rdickens: lnewson: np. though i'd forgotten about the "--latest" switch
(01:30:53 PM) lnewson: yeah jmorgan, using snapshot is equivilent to: pull-snapshot and then push
(01:31:21 PM) jmorgan: RGR
(01:31:28 PM) jmorgan: Will create a bug and get it documented.
(01:31:32 PM) jmorgan: cheers guys
(01:31:35 PM) lnewson: and adding the "--latest" option updates all frozen topics to their latest content
(01:31:51 PM) lnewson: otherwise anything with a revision number wouldn't get touched
(01:32:02 PM) rdickens: jmorgan: could you please assign that BZ to me? i'll make sure i get the docs updated
(01:32:25 PM) jmorgan: So once you do the command line argument, you need do keep doing that command line argument each time you make changes to that spec?
(01:32:53 PM) jmorgan: Each time you make changes to the topic XML featured in that spec.
(01:33:23 PM) rdickens: correct
(01:33:45 PM) jmorgan: Wow, so once you rev lock a book, you have a whole new workflow that needs to happen.
(01:33:53 PM) jmorgan: Why hasn't questions come up about this before?
(01:33:55 PM) lnewson: jmorgan, if you are using frozen content then yes. Generally though we had planned for it to only be frozen for a release and then to use unfrozen topics when working on development content
(01:33:57 PM) rdickens: "freezing" a content spec means the latest revision numbers are appended to each topic
(01:34:08 PM) lnewson: though if you are sharing topics it gets a lot more complicated
(01:34:24 PM) rdickens: lnewson: bingo! re: EAP 6 and EAP 7  :|
(01:34:50 PM) lnewson: yeah unfortunately :(
(01:34:50 PM) rdickens: jmorgan: umm.. it has, IIRC. this is where michelle documented how to branch docs using the CCMS
(01:35:01 PM) jmorgan: In the CCMS docs?
(01:35:17 PM) rdickens: jmorgan: that is, provided an illustration of how it should be done?
(01:35:35 PM) jmorgan: I'll say again, why not in the Handbook?
(01:35:45 PM) jmorgan: I know of that diagram.
(01:35:48 PM) rdickens: jmorgan: ah, i see what you mean. no, i don't there's been a definitive method documented
(01:36:06 PM) jmorgan: I found it pretty confusing.
(01:36:13 PM) lnewson: jmorgan, this maybe relevant to the bug you were talking about creating: https://bugzilla.redhat.com/show_bug.cgi?id=992338
(01:36:16 PM) rdickens: jmorgan: understandable
(01:38:16 PM) jmorgan: lnewson: So instead of trying to update the same csp spec, should we revision freeze that spec and create a new one for 6.1.1?
(01:38:39 PM) jmorgan: and then once we finish dev on 6.1.1 we freeze that spec and make a new one for 6.2?
(01:38:45 PM) lnewson: yeah, that was how we'd always thought writers would work
(01:38:46 PM) rdickens: jmorgan: so i understand, are you wanting documentation on how to do a async update to a book, perhaps because of errors that were not detected at GA?
(01:39:04 PM) lnewson: we just haven't got around to implementing the workflow for it yet
(01:39:07 PM) jmorgan: No the book has been frozen for 6.1 GA.
(01:39:18 PM) jmorgan: We now need to start documenting stuff for 6.1.1 
(01:39:27 PM) jmorgan: rdickens: 
(01:40:34 PM) rdickens: that's how EAP works - get to GA, copy spec for next product release, freeze spec for GA, publish documentation
(01:41:01 PM) kanchanD-wfh is now known as kanchanD-wfh-brb
(01:41:05 PM) jmorgan: Is there a way of removing all the [r: markers using csp on the command line
(01:41:14 PM) jmorgan: like "clean revisions" or something like that lnewson
(01:41:41 PM) lnewson: no but give me a sec and I'll give you a sed command that should remove them
(01:42:02 PM) jmorgan: Essentially, taking a snapshot of a csp map is like doing a svn branch command
(01:42:10 PM) zdover_brb is now known as zdover
(01:42:25 PM) jmorgan: you take a snapshot, then continue developing in /trunk, which is the CSP map without revision markers
(01:42:47 PM) lnewson: not quite, but it's similar
(01:43:00 PM) jmorgan: (this might be good to describe in the docs for those not familiar with ccms)
(01:43:12 PM) jmorgan: something they can grasp onto as a bridging concept
(01:43:17 PM) rdickens: misty intended that each book maintain the same content spec ID
(01:43:19 PM) lnewson: technically "csprocessor snapshot --new <ID>" would be closer to svn branching
(01:43:31 PM) rdickens: and that at release you freeze the spec and publish docs from that
(01:43:44 PM) jmorgan: OK.
(01:43:49 PM) jmorgan: So that's another approach to use.
(01:44:17 PM) jmorgan: so that command takes a snapshot, and assigns it a new ID that can be documented somewhere as a "cut for 6.1.0"
(01:44:20 PM) rdickens: yeah. personally i much prefer the freeze the spec, publish, create brand new spec for the next revision
(01:44:46 PM) jmorgan: why is that rdickens
(01:45:34 PM) jmorgan: snapshot --new ID would mean you wouldn't have to worry about stripping out all the [r:] cruft
(01:45:43 PM) jmorgan: from your /trunk content spec
(01:45:47 PM) rdickens: no particular reason. more a matter of preference.
(01:45:49 PM) slong_ is now known as slong
(01:46:15 PM) jmorgan: So you start from scratch each release rdickens.
(01:46:17 PM) rdickens: true, but i would make a clone of the spec before freezing it
(01:46:34 PM) jmorgan: OK. So we're getting some good procedural content here.
(01:46:36 PM) lnewson: yeah those are the two approaches available
(01:46:38 PM) rdickens: sorry. i *do* clone the spec before freezing it
(01:47:57 PM) lnewson: that way all the revisio history stays with the a specific release as well
(01:48:04 PM) lnewson: revision*
(01:48:38 PM) jmorgan: so snapshot --new ID isn't the preferred solution.
(01:48:43 PM) jmorgan: it is 
(01:48:54 PM) jmorgan: 1) Finish content development
(01:49:02 PM) jmorgan: 2) Clone spec
(01:49:08 PM) jmorgan: 3) Freeze Spec
(01:49:20 PM) rdickens: lnewson: you know, i hadn't thought about it that way.  :D  that's a little like what we have in SVN. we have recorded the history of each book per product revision
(01:49:21 PM) jmorgan: 4) continue docs development on cloned spec
(01:49:36 PM) rdickens: IMHO - yes
(01:49:37 PM) lnewson: atm it's entirely up to the docs team jmorgan, but I personally prefer that approach
(01:50:06 PM) jmorgan: how does revision history differ when you use snapshot --new ID
(01:50:16 PM) lnewson: we do need to work in a better workflow though so it's easier for everyone
(01:50:29 PM) jmorgan: Is revision history wiped when you snapshot and creat a new ID
(01:50:33 PM) jmorgan: read, a new spec
(01:50:35 PM) lnewson: --new means it creates an entirely new content spec with no history
(01:50:44 PM) jmorgan: Right, that is probably not a great idea.
Unknown command.
(01:51:00 PM) jmorgan:  /trunk would lose historical data
(01:51:16 PM) jmorgan: OK. Good info.