Red Hat Bugzilla – Bug 842951
RFE: host additional files needed for build in skynet
Last modified: 2014-10-19 19:01:09 EDT
At the moment you can override the Author_Group.xml and Revision_History.xml with arbitrary files when building, however it relies on the files being on your local computer.
What would work well is if these files could be stored in skynet so that the ability to build the book reproducibly is not tied to a specific machine.
Additionally, I and others use custom build scripts to manipulate the csprocessor built book in various ways to get functionality that isn't supported in csprocessor yet, but is necessary for production builds. These build scripts should ideally also be stored in skynet, again so that a book can built purely from skynet.
Currently there is no proper way to store this in skynet (without polluting the topic tables or StringConstants). There is also the matter that this is a temporary solution until we can implement revision log messages and better author group population. So for now these files will have to be shared via other methods.
Don't forget custom build scripts.
Ideally a csprocessor checkout should bring down everything needed to do a reproducible build of the document.
Anything that is custom is entirely your responsibility and won't be added intentionally at this stage. This is because if we start allowing these then we have to support them in some way/shape/form and as I've already said we have no mechanism to store them in Skynet.
Forgot to mention that the Author_Group.xml and Revision_History.xml are probably the only exemption to this rule since they are actual content. If you want to go around the normal builds and add custom content that isn't supported by us.
"we have no mechanism to store them in Skynet."
That's the RFE.
From a business requirements perspective: we have to be able to reproducibly build the documentation we release. If it's using custom build scripts, we have to track that somehow.
At the moment the best practice is to put the build scripts in svn and maintain instructions for building the doc somewhere (trac, svn). However, this means that if you just check the project out of Skynet, you may not be able to recreate a product release, especially if you don't discover the custom build sequence.
At the very least Skynet must have a mechanism for explicitly linking the projects to the build instructions.
"we have no mechanism to store them in Skynet."
If that's the RFE then it ain't going to go anywhere in this queue. As I've told you before any skynet changes need to go into the Skynet Bug queue. To me however the RFE is a two component RFE: 1) store custom content in Skynet & 2) use checkout to get the data and have a mechanism to upload the content into skynet.
I'm not going to move this or create a new RFE for now, as I'm going to talk this over in more depth with the team at the meeting tomorrow.
Also note that if you want that custom build script content stored, then you should make an RFE for it to be added to the builder, as it is probably missing usable features. That is the better way to do this and also it allows us to decide if it should be a supported feature.
As a temporary workaround you can write the details of how to build the book into the description field in Skynet for the Content Specification.
The absolutely last thing we want to have happen is for someone to leave, and then we find out one month later, when we have to do a critical security fix, that the custom build scripts for product X were on their encrypted hard drive, which has now been reformatted...
I'm sure you can think of some easy-to-achieve but effective way to make sure this doesn't happen (and no, "banning custom build scripts" isn't it ;-).
Maybe some way to explicitly link to them in svn or something.
And that is the exact reason you shouldn't be using custom scripts. What would you do if we weren't using a project in development? There would be no way to store that data either. As such you should try to avoid personalized custom content when building things that are to be released publicly. As I said though I'll talk it over more with the others as it's been a while since I got their input.
Also forgot to mention the call mainly relies on Matt and/or Darrin now a days, so I'll have to bring it up with them to get a final word. Currently the content is my opinion based on previous discussions with where we are heading and what we should be implementing.
Revision History also needs to be stored. Currently I'm working around it by putting the Revision History in svn and using wget to pull it down in my custom publish script.
I should add I brought this up at our meetings and the general consensus was an custom build items should be done through a tempting system rather than running scripts to modify builds and then uploading those scripts.
As I've already mentioned the Author_Group.xml and Revision_History.xml is an edge case that still needs working out.
Sorry for the typo, "tempting" should have been "templating"
I believe this is actually fixed now, or is captured in another bug.