On Fri, Jul 19, 2013 at 12:28 PM, Gary Martin <[email protected]>wrote:
> On 15/07/13 10:02, Ryan Ollos wrote: > >> On Sat, Jul 13, 2013 at 2:35 AM, Ryan Ollos <[email protected]> >> wrote: >> >> On Fri, Jul 12, 2013 at 9:01 AM, Olemis Lang <[email protected]> wrote: >>> >>> On 7/12/13, Ryan Ollos <[email protected]> wrote: >>>> >>>>> On Fri, Jul 12, 2013 at 2:53 AM, Branko Čibej <[email protected]> >>>>> >>>> wrote: >>>> >>>>> On 12.07.2013 01:48, Ryan Ollos wrote: >>>>>> >>>>>>> Adding the issue to the release notes will require creating a new >>>>>>> >>>>>> release, >>>>>> >>>>>> If that's the case, then we're doing something wrong. Release notes >>>>>> should not be part of the release tarball -- that should contain a >>>>>> /link/ to the release notes, so that any errata can be applied to the >>>>>> "live" release notes. >>>>>> >>>>>> Subversion keeps release notes in the project site repository. BH >>>>>> could >>>>>> have wiki pages with release notes -- only editable by committers, of >>>>>> course. >>>>>> >>>>>> -- Brane >>>>>> >>>>>> Keeping release notes on the wiki sounds good to me. >>>>> >>>>> fwiw + >>>> >>>> On a related note, at some point we should do something about our >>>>> >>>> diverging >>>> >>>>> installation instructions on the wiki (1) and in the repository (2). I >>>>> >>>> vote >>>> >>>>> for using the wiki in this case as well. This was recently brought to >>>>> >>>> our >>>> >>>>> attention again by a user (3). >>>>> >>>>> >>>>> (1) >>>>> https://issues.apache.org/**bloodhound/wiki/**BloodhoundInstall<https://issues.apache.org/bloodhound/wiki/BloodhoundInstall> >>>>> (2) >>>>> >>>> http://svn.apache.org/repos/**asf/bloodhound/trunk/** >>>> installer/README.rst<http://svn.apache.org/repos/asf/bloodhound/trunk/installer/README.rst> >>>> >>>>> (3) >>>>> http://markmail.org/message/**pa6go7siozxtouje<http://markmail.org/message/pa6go7siozxtouje> >>>>> >>>>> There's a recent conversation in trac-users ML that seems to be >>>> related >>>> to this >>>> >>>> http://www.gossamer-threads.**com/lists/trac/users/51772?**page=last<http://www.gossamer-threads.com/lists/trac/users/51772?page=last> >>>> http://www.gossamer-threads.**com/lists/trac/users/51804<http://www.gossamer-threads.com/lists/trac/users/51804> >>>> >>> >>> If everyone agrees to keeping the ReleaseNotes on the wiki, the next >>> steps >>> are: >>> [...] >>> >>> I also propose to merge any significant and relevant differences between >> README.rst in the repository and the BloodhoundInstall wiki page into the >> BloodhoundInstall wiki page, so that we have a single source of >> documentation. The file in the repository can point to the wiki page, as >> we >> propose to do for the ReleaseNotes. >> >> I'll wait until later this week before starting on any of these changes. >> Please try to raise any issues or alternative ideas you have before then. >> >> > While I think that it is a good idea to have the online pages as > canonical, personally I would probably generate the content of README and > RELEASE_NOTES in a release from the online pages. Adding a link to the > appropriate pages on the wiki, specifying those as where the most up to > date information will be would then make sense. Perhaps that is being over > cautious but, then again, I have not noticed any open source projects where > a RELEASE_NOTES or CHANGES file was not part of the source package. My > survey is probably not wide enough though. > > Talking of all this, we are obviously going to have to start maintaining a > set of online versions of pages at some point so it might be worth taking > that into account with whichever approach we take. > > Cheers, > Gary > I think that probably makes sense. If the release notes and install steps are pulled from the wiki in plain text, they should be fairly readable, however we could also look into exporting them as HTML (might require installing a plugin on i.a.o), or using ReST markup on the wiki page (using the rst wiki processor) and formatting to HTML after the plain text is exported and the WikiProcessor stripped from the page content. The downside to using ReST is having yet another markup language, and possibly making it more difficult for users to contribute to BloodhoundInstall. Does anyone have suggestions on which might work better?
