On Feb 12, 2015, at 1:38 AM, Pete Travis <me@xxxxxxxxxxxxxx> wrote: > On 02/11/2015 03:27 PM, Brian (bex) Exelbierd wrote: >> On Feb 11, 2015, at 3:53 PM, Pete Travis <me@xxxxxxxxxxxxxx> wrote: >>> - It should be simpler to make drafts available. If we can automate >>> publishing on release branches, we can do the same with master. >> Addressed below with Jenkinscat :) I’d also like to see an easy way for individuals to see their non-master committed work in a stage environment. I don’t think the answer lies in local builds though as they aren’t shareable. Pulling this off will almost certainly require us to be willing to consider a modification to our branching strategy. I have ideas here, if there is interest. > Interest, yes! I don't see a way around "release" branches, but I do > like the idea of shared work branches, if that's what you're getting at. It is :) Jenkinscat should be able to be easily extended in this direction … I will try to draw up some of my ideas during a long train trip this weekend .. but no promises. >>> - There should be an effective way to publish and organize sundry >>> articles. >> I would encourage us to think about a single publication system here. Therefore the challenge is how to present the articles, not how to publish them. The articles can all live in a single repo and all be republished when one changes. The right publication means this isn’t a problem. I am doing this with some non-Fedora docs now and the runtime is trivial (markdown -> html). > Right, the presentation is what needs the most work, the front end that > users will browse through to get to the individual articles and guides. I think the answer to this lies in having someone think about presentation without thinking at all about where the content comes from. Perhaps the folks in the Marketing Project can help us here? > There are both tooling and design challenges there. but, erm... single > repo? like web.git? Maybe I'm misunderstanding you, but nobody wants to > keep that around :P On this other project, we have a single repo that holds a small collection of markdown documents. These documents are all processed and published to a separate documentation area from our main documentation which is in DocBook (and typically in a 1:1 repo:book format). This has the advantage of just feeling cleaner. I believe, but must confess not having paid enough attention back when I had free time, that web.git is the “master” repo for the website. That scares me too :) >>> - The publishing platform should be able to process arbitrary markup >>> formats. I think docbook is great, and publican does a good job with >>> it, but there will be room for more contributions if that isn't mandatory. >> This is the biggest challenge, after design, IMHO. >> >> I have not yet found a great multi-input publishing mechanism. Pandoc comes close, but has some serious shortcomings in some input formats. Additionally, being written in Haskell, it is harder to find people who can extend it (in my experience). Additionally, even if that works you still have to deal with branding. Asciidoctor is supposed to be better, and rst via sphinx and others is also great. Lastly, there are engines like Jekyll which might be a good fit too. >> >> Here I think we need to either make some arbitrary decisions (i.e. we support only x and y, or we only support this subset of markup z, etc.) or risk having to support a lot of conversion engines. My suggestion for today is to try to define the minimal markup needs for our publication chain and i18n and then choose two markups (Docbook and ???) and move forward. >> >> As a start on minimal markup needs, it sounds like we need entity support, possibly xinclude-style insertions, and a way to flag material that shouldn’t be translated. We also need to decide whether we will allow non-semantic markup. If we can ensure strong reviews and/or gating on publication, non-semantic markup can be made to work. >> >> I’d also like to see us consider a way to easily enable drive-by contribution and editing. I’ve been working on an architecture for a different project that has similar requirements. It currently exists mostly in my mind, but I hope to get it into writing and demo mode soon. >> > > I really don't want to get hung up on support for additional formats at > this stage. Given tooling to dynamically build a front end, it > shouldn't be a problem to add support for whatever format. Jenkins can > probably handle whatever we throw at it, we can work out the tooling to > build other formats after the core solution in place. I agree that we start with DocBook. But I think we architect for 2 markups. That will force us to think through the ramifications of our choices. >>> The working theory at this point is to use a continuous integration >>> system like Jenkins to automate builds. I've had a Jenkins instance >>> running locally this week, with new builds triggered via fedmsg signals >>> generated by our commits. This part works smoothly, with the exception >>> of a fedwatch bug that I've crudely worked around, but triggers using >>> python-fedmsg really wouldn't be too difficult. >> This is fantastic. I read this as you suggesting we can do both stage and publish on this platform. > Sure, we could definitely have ie drafts.docs.fedoraproject.org that's > built from master, or with navigable content from feature work branches, > etc. For now, it is probably best limit the scope to a public-facing > solution, then iterate. Alternately, we can build the drafts site and use that to iterate a design that works for the public site. However, I can’t help but wonder if we shouldn’t split the task. drafts.docs.fp.o is a stage for docs.fp.o. Nothing more. Jenkinscat provides all other staging. This way stage and prod never behave differently. >>> The infra folks are >>> also working on a Jenkins setup, so there's potential to share >>> experience and buildslaves. Turning that into a browseable frontend is >>> more immediately viable than you might think; >>> http://sourceforge.net/projects/jenkinscat/ is designed just for that >>> and can be customized for our needs. >> Leverage CI: +1 >> >>> Jenkins plugins to cycle strings >>> from Zanata, or some other method, could come down the road. There's >>> room for other enhancements, too. >> I’d love to hear from the i18n folks how they’d like to see this. Do they want continuous updates or to work on a cadence? > I wrote plugins, then actually started looking into it and talked to > #zanata, and all we need to do is use the normal zanata cli tools as > part of the Jenkins build job. The Jenkins git plugin has some features > to merge-on-success we could leverage. > > The loudest voice here has been Jerome Fenal from the very active > French team, and he advocates a continuous flow. In a practical sense, > we can set the master branch to push to master on Zanata, the F21 branch > for F21 on zanata, etc; translators that want the continuous flow can > work on master, those that want something more curated can work on the > release branches. If Zanata's translation memory works like it did for > Transifex, the translations for identical strings will automatically be > available for all branches, no redundant translation required. That makes sense. I’d like to see some idea of workflow from the translators about when to decide something is publishable. Regardless, it sounds like the workflow from our perspective is simple. We land final content in a branch in a repo. That repo is set to branch and copy as required by the translator workflow. We can help them implement but we don’t have to worry about the workflow as part of our solution. Frankly, I know it is simple to say/think, but it really helps me to think of the workflow as having hard edges that are settled by negotiations at each hand off. Writing (including reviews) -> candidacy for publication (potential material) -> submitted to translation | staged -> published regards, bex -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
