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.*
