| Summary: | Need updated doc publishing process in Makefiles and Yocto Project website | ||
|---|---|---|---|
| Product: | [Documentation] Quick Start | Reporter: | Scott Rifenbark <srifenbark> |
| Component: | quick-start | Assignee: | Saul Wold <sgw> |
| Status: | RESOLVED FIXED | QA Contact: | |
| Severity: | critical | ||
| Priority: | High | CC: | david.c.stewart, elizabeth.flanagan, jefro, julie.n.fleischer, poky.doc.watcher, poky.watcher, richard.purdie, sgw |
| Version: | 1.0 | ||
| Target Milestone: | 1.0 PointRelease | ||
| Hardware: | Other | ||
| OS: | Multiple | ||
| Whiteboard: | Patch pending integration (5-May-2011) | ||
| OS type for building Yocto: | --- | Type of Regression: | --- |
| Verified: | Documentation change: | --- | |
|
Description
Scott Rifenbark
2011-04-06 08:37:56 UTC
Need engineering or IT support to be able to get this going. Unless I am missing something here the solution seems pretty simple. Just need some permissions to publish stuff into the drupal site hosting the yocto website. Hi Scott - Mike may be able to set this up. I'm assuming the needed permissions are just for you, not for everyone, right? I had a question, though, about whether it is a good idea to autopublish on every make. Is there a process to vet the docs before publishing? In past projects I have set up "make install" to publish the docs, but running "make" just builds locally. Maybe I am misunderstanding the process. I don't know who the permissions are required for... This is the part I am unfamiliar with. I would assume that would work though. Regarding publishing on every make I don't see a problem with that as that would make sure the docs on the website are always most recent. I'm still not sure I understand. Every time someone downloads poky and builds it, they publish documentation to the main website? That opens up security concerns in addition to quality concerns. I would strongly recommend changing the Makefile to require a second step to publish documentation to the main site, and some vetting process. I love transparency and community inclusion, but there has to be some gatekeeping process. Imagine if everyone who downloaded and built the Linux kernel also posted it to kernel.org every time they typed "make". Good point... I did not think of the world working on the docs. I was lost in my little closed process of my own. Maybe I should talk to you and we can think this thing out a bit.... To fix this bug we will remove the publish option from all the documentation make files. these were publishing to o-hand and were broke anyway. then we will create a local script that can be executed to push the most recent HTML documentation files to the Yocto Project website. The local script can be run at our convenience when we are satisfied with the quality of community patches and internal work regarding the docs. After further discussion with RP it appears that we do not need a separate local script to publish or push the HTML files to the Yocto Project website. Evidently the ssh key can be used to restrict access to the website. So, the fix for this bug will be making sure the ssh key and permissions are set up correctly and then changing the publish statements in each document's make file. They currently attempt to publish to o-hand. I am waiting on RP's assistance to complete this bug. Saul and Beth to work with ScottR to get the permissions on the server and the ssh key stuff straightened out and working. ScottR to make changes to the Makefiles for the manuals. A few things we need to discuss here, Scott. 1. Switching the URL/giving you access can happen today. I'll ping you on IRC 2. That said, the doc publishing has some process issues: - We have no history wrt doc publishing. So, for example, we can't go back to, say, laverne docs. Going forward, this needs to be fixed. We should have something like: www.yoctoproject.org/documentation/1.0/<docname> www.yoctoproject.org/documentation/current/<docname> (symlink to most recent documentation) This will allow us to have docs that support prior releases. - We're really talking about two release processes here. You need the ability to update documentation that exists, should a bug be found (like a bug in bernard documentation, for example). You also need the ability to release new documentation (like 1.1). This is fairly easy to accomplish and should be brought into the release process. Let's talk about this. I've put a feature on the 1.1 list to bring this into the release process. I've got the server side of this fixed for the time being. However this should be an rsync, not an scp. A good portion of the publishing functionality should be brought into the release process. I'm going to open another bug on this to track that portion. I have the Makefile issues worked out and two of the five manuals are working with the changes pushed to yocto-docs. I will close on this when the other three manuals are good. All changes have been committed and pushed to the yocto-docs repo to satisfy this bug. The publish process for all five YP manuals now works so that when I run it the HTML and PDF versions of the manuals (along with related style sheets and PNG files) are pushed to the Yocto Project website into the appropriate documentation folder structure. Once the yocto-docs repo is merged with the poky repo by Saul or RP the bug can be closed. http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=92690ef3cca0575fc84819129306b913c7e995df http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=f55fec8703a18b56e7ba7f75b90c9f5b276016f3 http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=f7b1705ef38212dd59a568b4afaca56c2402d825 Bernard: http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=36c91352155617cc6ee3a975b3ced5fb026d1e3b http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=437950723f7bd0d18e4fdf46d4c678a086ccd361 http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=5f92b6262f5d902b4212258f0291fe065e534474 http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=65d61e2d113d70acf0c351aadbdd65b6b0e59bb4 |