Hi, +1 on this last.
This makes sense to me, so long as it's aligned with the criteria for Apache incubating projects. This makes it easier for folks to contribute documentation changes that are versioned, and to change the website framework, so win-win.. I definitely agree we need to keep versioned documentation with the actual software and update that in conjunction with checkins. That's separate from keeping older documentation versions accessible, especially for current recommended versions versus daily-build-ish updates. We can't expect everyone to jump to the latest daily build, even if we keep the documentation more up to date. -Carol P. On Tue, Nov 17, 2015 at 5:44 PM, Gunnar Tapper <[email protected]> wrote: > So: > > > - Web site in single branch of main repo > - Generate documents from master, publish to release-specific landing > pages > - Generate web site, which pulls in the release-specific landing pages > > ? > > On Tue, Nov 17, 2015 at 6:31 PM, Venkat Muthuswamy < > [email protected]> wrote: > > > I agree with Steve. The product documentation is tied to the source > version > > and should stay with the code repository. > > > > The artifacts from the product build can be staged some place before the > > website is built. > > We can probably script that part that pulls in the necessary > documentation > > files together. > > > > Venkat > > > > -----Original Message----- > > From: Steve Varnau [mailto:[email protected]] > > Sent: Tuesday, November 17, 2015 5:04 PM > > To: [email protected] > > Subject: RE: Website Updates > > > > Thanks, I thought that may be the case. It is location for publishing to > > the staging and published sites. > > > > So the source ought to be in our main repo, but can be single branch > > (either > > master or a branch just for web). > > > > If the maven build of the site needs docs from multiple releases, then > that > > gluing together would have happen when prepping/generating the site, > right? > > > > --Steve > > > > > > > -----Original Message----- > > > From: Gunnar Tapper [mailto:[email protected]] > > > Sent: Tuesday, November 17, 2015 4:46 PM > > > To: [email protected] > > > Subject: Re: Website Updates > > > > > > That's a copy of the docs/target directory in the build. No source > files. > > > > > > On Tue, Nov 17, 2015 at 5:44 PM, Steve Varnau <[email protected]> > > > wrote: > > > > > > > Seems to me that product documentation should be versioned with the > > > > product. > > > > > > > > Whereas there needs to be one web site that refers to multiple > > > > versions of the product and docs. > > > > > > > > The project web site exists in incubator-trafodion-site repo, > correct? > > > > Or > > > > is that just the staging location? > > > > https://git-wip-us.apache.org/repos/asf/incubator-trafodion-site > > > > > > > > --Steve > > > > > > > > > > > > > -----Original Message----- > > > > > From: Gunnar Tapper [mailto:[email protected]] > > > > > Sent: Tuesday, November 17, 2015 4:28 PM > > > > > To: [email protected] > > > > > Subject: Re: Website Updates > > > > > > > > > > Hi, > > > > > > > > > > My original suggestion was to separate out the web site and the > > > > > documentation. Would that work given how; for example, the DCS > > > > > asciidoc > > > > is > > > > > part of dcs/src/main/asciidoc? > > > > > > > > > > I believe that we can look at how other projects separate out > > > > > these items for guidance. There will be a need to update the > > > > > website for new release but that seems manageable in comparison to > > > > > the current situation. > > > > > Refer > > > > to > > > > > https://geode.incubator.apache.org/contribute/ for how that > > > > > project handles documentation and the website. > > > > > > > > > > The question about artifacts seems to depend on the DCS > > > > > documentation issue. You either move those files to the new source > > > > > tree or you have to copy to a known place for the website to pick > > > > > them up. > > > > > > > > > > Thanks, > > > > > > > > > > Gunnar > > > > > > > > > > > > > > > > > > > > On Tue, Nov 17, 2015 at 5:03 PM, Roberta Marton > > > > > <[email protected]> > > > > > wrote: > > > > > > > > > > > +1 - we do need to update the website and other artifacts > > > > > > +separately > > > > > > from > > > > > > the main code and I would create a JIRA and file it under build > > > > > > infrastructure. > > > > > > > > > > > > Some questions to ponder: . Have you given thought to how the > > > > > > website changes will be separated from the Trafodion product > > > > > > changes? Will there be a separate repository and how will the > > > > > > repository be maintained? > > > > > > Also, > > > > > > will > > > > > > the new repository only contain website changes? Will this also > > > > > > be a good place to put documentation changes - as Hans > > > > > > mentioned? When we > > > > release > > > > > > Apache artifacts, do we also have to release the documentation > > > > > > (don't think so)? > > > > > > > > > > > > Roberta > > > > > > > > > > > > -----Original Message----- > > > > > > From: Gunnar Tapper [mailto:[email protected]] > > > > > > Sent: Tuesday, November 17, 2015 3:51 PM > > > > > > To: [email protected] > > > > > > Subject: Re: Website Updates > > > > > > > > > > > > Great. Should I create a jira to create a new docs branch? > > > > > > > > > > > > Thanks, > > > > > > > > > > > > Gunnar > > > > > > > > > > > > On Tue, Nov 17, 2015 at 4:48 PM, Hans Zeller > > > > > > <[email protected]> > > > > > > wrote: > > > > > > > > > > > > > +1 > > > > > > > > > > > > > > Another thing I noticed with other sites, the Javadoc pages > > > > > > > seem to > > > > be > > > > > > > available only for the latest release (at least that was my > > > > > > > impression). It might be good to make those and other > > > > > > > reference information like manuals available for older versions > > as > > > > > > > well. > > > > > > > > > > > > > > Another dimension is whether we put info on a static page vs. > > > > > > > a wiki where people can edit and comment. Apache requires > > > > > > > certain things to be on a page managed by source control, but > > > > > > > IMHO it would be nice to have other info on a wiki, with > > > > > > > discussions right near the page with the relevant content, so > > > > > > > people can see and discuss common problems and their > > > > > > > solutions. Also, the speed is much faster. Even if we put the > > > > > > > non-wiki site in a separate repository, some rules for > > > > > > > committing changes to it may still apply. > > > > > > > > > > > > > > Hans > > > > > > > > > > > > > > On Tue, Nov 17, 2015 at 3:33 PM, Christophe LeRouzo > > > <[email protected]> > > > > > > > wrote: > > > > > > > > > > > > > > > +1 > > > > > > > > > > > > > > > > It can also enable different kind of contributions than the > > > > > > > > ones on the code itself. > > > > > > > > > > > > > > > > Regards, > > > > > > > > -clr > > > > > > > > > > > > > > > > > > > > > > > > -----Original Message----- > > > > > > > > From: Amanda Moran [mailto:[email protected]] > > > > > > > > Sent: Tuesday, November 17, 2015 3:18 PM > > > > > > > > To: dev <[email protected]> > > > > > > > > Subject: Re: Website Updates > > > > > > > > > > > > > > > > +1 > > > > > > > > > > > > > > > > Makes sense to me. > > > > > > > > > > > > > > > > Thanks Gunnar. > > > > > > > > > > > > > > > > On Tue, Nov 17, 2015 at 3:15 PM, Gunnar Tapper > > > > > > > > <[email protected]> > > > > > > > > wrote: > > > > > > > > > > > > > > > > > Hi, > > > > > > > > > > > > > > > > > > As it turns out, we immediately hit issues with having the > > > > website > > > > > > > > > as part of the product source tree. > > > > > > > > > > > > > > > > > > The website is really a standalone entity that operates at > > > > > > > > > a different speed than the product and that should be on a > > > > different > > > > > > > > > release schedule than the overall product. > > > > > > > > > > > > > > > > > > The speed issue is that the review-then-commit model has > > > > > > > > > long delays built in, which are counter productive for > > > > > > > > > website development (since that development tends to be > > > > > > > > > sporatic and > > > > > > > > > clustered) thereby slowing down the updates and and > > > > > > > > > forcing huge commits instead of incremental commits. The > > > > > > > > > tie to a release is really odd since a website update is > > > > > > > > > forcefully tied to a product release in such a model. A > > > > > > > > > workaround would be to publish the content of the > > > > > > > > > docs/target directory before the in-progress release is > > > > > > > > > done, which doesn't really follow the spirit of > > > > release > > > > > > > > > versions. If anything, the website should have it's > > > > > > > own > > > > > > > > > version scheme. > > > > > > > > > > > > > > > > > > Given the precedence of other projects separating out the > > > > > > > > > website and documentation, then it seems reasonable to do > > > > > > > > > the same from Trafodion. > > > > > > > > > I assume that the committers votes on this? Is a Jira > > > > > > > > > needed or some other approach? > > > > > > > > > > > > > > > > > > Thanks, > > > > > > > > > > > > > > > > > > Gunnar > > > > > > > > > > > > > > > > > > On Tue, Nov 10, 2015 at 5:15 PM, Dave Birdsall > > > > > > > > > <[email protected]> > > > > > > > > > wrote: > > > > > > > > > > > > > > > > > > > Hi, > > > > > > > > > > > > > > > > > > > > Just thinking out loud. > > > > > > > > > > > > > > > > > > > > Pros to keeping just one repository: > > > > > > > > > > > > > > > > > > > > Makes it possible to update code and web site in one > > > > > > > > > > pull request. I > > > > > > > > > don't > > > > > > > > > > know anyone who is doing that now however. Longer term, > > > though, > > > > > > > > > > we will want to encourage documentation to be updated > > > > > > > > > > alongside code so this may be > > > > > > > > > the > > > > > > > > > > direction we want to go. > > > > > > > > > > > > > > > > > > > > Makes it easier to have a notion of code + web site > > > > > > > > > > being on > > > > the > > > > > > > > > > same release thread. Of course that can still be done > > > > > > > > > > with separate repositories; it is just twice the work > > > > > > > > > > from an infrastructure perspective. > > > > > > > > > > > > > > > > > > > > Pros for having separate repositories: > > > > > > > > > > > > > > > > > > > > Makes it easier for the web site to be "pan-release". > > > > > > > > > > For example, one > > > > > > > > > can > > > > > > > > > > maintain separate pages for past releases and pages for > > > > > > > > > > future > > > > > > > > releases. > > > > > > > > > > > > > > > > > > > > It might be interesting to inquire of other projects why > > > > > > > > > > they > > > > do > > > > > > > > > > things > > > > > > > > > the > > > > > > > > > > way they do. > > > > > > > > > > > > > > > > > > > > Dave > > > > > > > > > > > > > > > > > > > > -----Original Message----- > > > > > > > > > > From: Gunnar Tapper [mailto:[email protected]] > > > > > > > > > > Sent: Tuesday, November 10, 2015 3:59 PM > > > > > > > > > > To: [email protected] > > > > > > > > > > Subject: Website Updates > > > > > > > > > > > > > > > > > > > > Hi folks: > > > > > > > > > > > > > > > > > > > > I'm working on updating the website. As I look around, I > > > > > > > > > > find that some projects seem to have a separate > > > > > > > > > > repository for the website. I assume > > > > > > > > > that > > > > > > > > > > it's so that the website can be updated asynchronously > > > > > > > > > > from the actual project. > > > > > > > > > > > > > > > > > > > > Examples: > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > - http://phoenix.apache.org/building_website.html > > > > > > > > > > - https://geode.incubator.apache.org/contribute/ > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > What would be the pros and cons you'd see for Apache > > > > > > > > > > Trafodion? > > > > > > > > > > Is anyone dead against a separate repository for the > > > > > > > > > > website? > > > > > > > > > > > > > > > > > > > > -- > > > > > > > > > > Thanks, > > > > > > > > > > > > > > > > > > > > Gunnar > > > > > > > > > > *If you think you can you can, if you think you can't > > > > > > > > > > you're > > > > > > > > > > right.* > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > -- > > > > > > > > > Thanks, > > > > > > > > > > > > > > > > > > Gunnar > > > > > > > > > *If you think you can you can, if you think you can't > > > > > > > > > you're > > > > > > > > > right.* > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > -- > > > > > > > > Thanks, > > > > > > > > > > > > > > > > Amanda Moran > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > -- > > > > > > Thanks, > > > > > > > > > > > > Gunnar > > > > > > *If you think you can you can, if you think you can't you're > > > > > > right.* > > > > > > > > > > > > > > > > > > > > > > > > > > -- > > > > > Thanks, > > > > > > > > > > Gunnar > > > > > *If you think you can you can, if you think you can't you're > > > > > right.* > > > > > > > > > > > > > > > > -- > > > Thank you, > > > > > > Gunnar Tapper > > > Presales Manager > > > Esgyn Corp. > > > > > > -- > Thanks, > > Gunnar > *If you think you can you can, if you think you can't you're right.* >
