=====Discussion about adding WikkaReleaseNotes at the time of installation=====

~&Why not adding WikkaReleaseNotes as a default page (or at least the section on what's new in the last version). As an alternative, (minimal solution) we might add a link to the WikkaReleaseNotes page on the wikka server;
~~&I'd wager that the average Wikka owner does not care as much as you and I do about the release notes.  Have you noticed that the majority of Wikka sites that have been around for a while have never upgraded? Anyhow, how about an alternative:
~~&We can still have a page named WikkaReleaseNotes, but we bring back what Wakka used to do. Create an action named wikkachanges. This action will display a file in the docs directory named CHANGES.txt. We then put the action in the WikkaReleaseNotes page. This way we cover two areas: admins who have just downloaded the distribution file, and online users who want to see the changes.  The wikkachanges action is live on this site right now. Try it.

~~&''I saw it in the SandBox and it messed up things royally there... disabled it, and added notes about my findings.---I agree with Dartar, I'd like to see WikkaReleaseNotes included as a default page; if one doesn't look at it, fine, but at least it's there if you do need to consult what was changed (and why) and it's much more readable than what ""{{wikkachanges}}"" produces. I'd vote for just removing the ""{{wikkachanges}}"" action and simply including a WikkaReleaseNotes page. --JavaWoman''

~~&Have both of you thought how this would be implemented?? It's easy to include a default page on install.  However, what are we going to do on upgrade? Are we going to overwrite the page? (''Yes, of course! And that's what you'd do with a text file as well - what's the difference?'') What if the site has changed the page? (''Include a note on the page that it is a system page that **will** be overwritten on upgrade; if possible protect the page from editing by anyone but admin on install.'')  I think it would be annoying for the upgrade script to overwrite an existing page. (''But you //would// be overwriting the text file - what's the difference? A page is just a more readable version. And we wouldn;'t need to keep the same information synchronbized in two places - always a bad idea.'') Hence the solution that I have proposed. In addition, how long is it going to be before someone says, "Hey, why don't we include a text file that lists the changes". (''Maybe **very** long - it hasn't happened, has it? See how it goes.'') Once again, we take care of this by including the text file and then showing it in the wiki. Sites are not going to update the Wikka release notes--it's static data. Why have it as a wiki page? (''For readability, and it fits in simply with the system. Yes, sites are not going to update the release notes - in whatever form. And if they **do** want to update them, they could do that with the text file just as easily.'')
~~~&''My 2 cents. On the one hand, I agree with JW as far as //readability// is concerned: it is much better to have a formatted version, with headers etc., possibly with links, than a plain-text version (the first thing I thought when I saw the SandBox page full of raw text was : "gosh, the formatters are broken!"). This said, there is a question that none of you has mentioned so far. How are we going to deal with //internal links// that are present in the current WikkaReleaseNotes page? Either we distribute a version of WikkaReleaseNotes with no internal links and no camelcase words left or we have to think of a solution to avoid generating a ton of missing pages. IMO, one interesting solution (which might require some futher development, though) is to use a [[IncludeRemote | FetchRemote]] strategy to retrieve fresh and uptodate documentation on the new release from the main server (JsnX, have you tried to install the plugin locally?). This has the advantage of avoiding writing a hardcoded page in the user's database and - as Jason was suggesting - let the user free to decide where to add the release notes (it is just a matter of adding somewhere ##""{{fetchremote page="WikkaReleaseNotes")""##). On the other hand, I was wondering: is there really a problem with //overwriting// an existing page? Provided the installer says explicitly it is going to overwrite one page, this page will be nothing more than a //version// of the page (that's the power of wikis!): if a note is added like "updated by the Wikka installer", the user will always be able to retrieve previous versions of the same page if needed. So I don't really think that overwriting is a problem. -- DarTar'' 

~~~~&Sorry to keep hammering on this, BUT :), let's see how your logic holds up:
~~~~~&Is there really a problem with //overwriting// an existing HomePage? Provided the installer says it is going to overwrite the HomePage, the new HomePage will be nothing more than a //version// of the page. The site admin will always be able to retrieve the previous version of the HomePage if needed. So I don't really think that overwriting the HomePage is a problem.
~~~~&Sounds absurd, doesn't it?
~~~~~&''Um, yes. What goes for the HomePage goes for the WikkaReleaseNotes: "overwriting" simply means creating a new version in the database. So I don't really think that's a problem. ;-) --JW''
~~~~~~&
~~~~~~&''As I said above, I don't consider this a problem. But even if you don't agree with this, consider that no one is proposing here to overwrite a page like HomePage, but a page with a sufficiently clear 'system default' name (like WikkaReleaseNotes) that will hardly be modified by Wikka users (and if it is, again, it's just a version..). -- DarTar''

~~~~&Regarding JavaWoman's comments: 
~~~~~&Your first point was that the installer would overwrite the text file, so why not overwrite a page.
~~~~~~&That's not correct. **The site admin** would overwrite the text file, by his choice of uploading the new file to the webserver. It would be his choice to overwrite the file. See the difference?
~~~~~~&''Most site admins would not "upload the [separate] files" but rather upload the archive to the server, untar it there, and then run the upgrade routine. Just untarring would replace all files. And why would one //not// replace a release notes (text) file? It contains all previous information, doesn't it?''
~~~~~&Your next point was that it's a bad idea to keep the information in two places.
~~~~~~&So you are suggesting that we should only make the information available online and **after the upgrade has already happened.** Wouldn't you want to know what has changed **before** you upgrade?
~~~~~~&''It **is** known **before** you upgrade because it's right here. --JW''
~~~~~&I could go on and on. The bottom line: it's standard for software distributions to include a text file that describes changes. This is where most people will look for the information....and they will want to review the changes before they decide to upgrade--not upgrade and then review what has changed.  I'm in favor of using ""{{fetchremote}}"" to make the information available online, but also including a text file that can be reviewed offline. Here's an example of how the text file might be useful: Let's say an upgrade breaks an existing site. The admin could view the text file to help narrow his focus for fixing the problem.  ... I'm going to throw in one more thing just to preempt it: But couldn't the site admin just view the release notes on WikkaWiki? That's possible, however this site might be down. It could be down from a denial-of-service attack.  I could be dead and thus not able to pay the bill.  Who knows?  By including a text file we won't have to worry about any of this.  -- JsnX
~~~~~&''Actually, many applications have all their documentation online, except maybe a small readme and a license file. Most people don't download first, then unpack an archive, and then read a changes file to see what's in the latest release: they read the release notes online **before even downloading**. Sure a site can be down - that can always happen. Many possible causes (and it happens to the best of them). //As to you being dead and not being able to pay the bill - that's an entirely different discussion (one we should have, about continuity and how to ensure it, but not here in this context).// But the whole idea of including release notes is to provide a reference //after// download and installation - but that won't normally happen until **after** one has checked the release notes online to see whether it's worth the download in the first place.---My argument about keeping the information in two different places and two different formats identical still stands, meanwhile - how do you propose to make sure the two versions have identical information at all times? Even if you have a reliable procedure for that (you'll need a script) - it's extra (unneeded) work, as is creating a special action to show the contents of the text file: two files, two programs, all to show the same content? A simple page that (for now) shows just a link or (later) pulls the content directly from the site will be much simpler. -- JavaWoman''
~~~~~~&
~~~~~~&''Regarding this point, I don't agree with  JW's argument. I think a text version with the release notes, accessible to the Wikka administrator before untarring and uploading the package makes perfectly sense (and actually is very common in software distributions). I really don't see the problem with "keeping information in two places": before releasing a new version, the text release notes can be created in 5 seconds  just by copying and pasting in a text editor the formatted output of WikkaReleaseNotes. So where's the problem? -- DarTar''

~~~~~&''In referring to "keeping information in two places" I'm thinking of a build process, assuming (not the case now!) that **all** the to-be-released files are in a CVS branch, and you just run a script to turn that into a distribution. The files in that branch should -at all times- be up-to-date, which includes any text files to be included. So what happens while you're working on a new release? Something like this - for **every change to be made for the next release**:
~~~~~~&- apply a fix or create/add a new extension
~~~~~~&- make a corresponding note in WikkaReleaseNotes here
~~~~~~&- make a new copy of WikkaReleaseNotes to 'changes' text file
~~~~~~&- commit all these files into the CVS---
~~~~~~&....
~~~~~~&- build (periodically) new beta release or (once) final release
~~~~~&The set of files in the repository should be "complete" at all times to be able to do a build; which (in your proposal) means also //repeatedly// copying the WikkaReleaseNotes (manually, or via a script) - not just once, but for every change being made. It's an extra step, and doing that step is a manual process (even if you run a script to do the copying, running the script is a manual step). People do forget steps :), so the fewer manual steps there are, the more reliable the build and release process will be.''

~~~~~&''On the other hand, a static WikkaReleaseNotes page with a link to the online WikkaReleaseNotes would need to be created and committed only once; no redundant and easy-to-forget manual steps needed any more. --JavaWoman''

~~&Why don't we focus our energy on making the ""{{wikkachanges}}"" action better? JavaWoman, you are detailing problems with my crappy action that I spent ten minutes on to demonstrate the concept. Wouldn't it be possible to tweak the action to output the text to your satisfaction? (''What I see is is a far less readable version, and if it's in a text file, then how are you going to keep the two synchronized? We **already** have WikkaReleaseNotes - if you just include that it's simpler (it's already there), more reliable (nothing to synchronise, the data is in one place, not two), and more readable (no extra action needed either).'')

~~&I'm proposing that we name the page WikkaReleaseNotes for a reason.  Let's imagine that Linus decides he wants to create a Wikka site name LinuxWiki to document his Linux kernel.  If we name a default page as WikkaReleaseNotes, won't this confuse people on the LinuxWiki site when they are looking for the release notes for Linux? What will Linus name the page that describes the release notes for his software?  You might say, he could just overwrite the Wikka release notes with whatever he wants.  But then what happens when he upgrades to a new Wikka version?  Do you see the problem that we are creating? (''So rename it WikkaReleaseNotes **here** and include **that** page as a system page. I agree that the name is not optimal - but the same is true here already. **Note**: this rename has been done now --JW'')

~~&I don't like the idea of us forcing pages on people. If we make the release notes as an action, people can have the release notes show on any page they want. They could create a page named WikiEngineChanges and place the ""{{wikkachanges}}"" action on it, and when they upgrade, the changes will show up on the page that **they** decided. (''So they create a page called WikiEngineChanges and just ""{{include}}"" the WikkaReleaseNotes on it.'')  If we force a page named WikkaReleaseNotes, we are going to create an unnecessary struggle with site owners that might not want to have the Wikka release notes on a page named WikkaReleaseNotes. (''It's just another "system" page, like SandBox and FormattingRules. I don't see the problem.'')  -- JsnX 

~~&''Comments embedded above to make them more relevant to context -- JavaWoman''

~~&''I gave above some more reactions about my way of seeing the problem of release notes. I'd like to propose here some steps towards a solution that I hope we might all agree upon.
~~&- we rename the ""ReleaseNotes"" page on this server as WikkaReleaseNotes; **Note**: done now --JW
~~&- we add to the next release the ##""{{version}}""## action;
~~&- we create a (temporary) ##""{{wikkachanges}}""## action that prints the following code:''
~~&%%===== Wikka Release Notes ===== 
This server runs on [[[http://wikka.jsnx.com/ | Wikka Wiki]] version **{{version}}**.
The new features of the current version are described on the [[http://wikka.jsnx.com/WikkaReleaseNotes | main Wikka server]]%%
~~&''In the future, this action will be replaced by a FetchRemote action.
~~&(BTW it might be interesting to add named anchors in WikkaReleaseNotes to facilitate referring to specific Wikka versions)
~~& - we add to the installer/upgrader a line for creating a local WikkaReleaseNotes. The page will contain, for the time being, only ##""{{wikkachanges}}""##. The installer leaves a note about the page creation/upgrade: "written by the Wikka Installer"; 
~~& - we distribute with each release a text file, called ##docs/WikkaReleaseNotes.text## with a textual version of the section of WikkaRecentChanges page on the main wikka server concerning the last release.
~~&
~~& Is this an acceptable compromise? ;) -- DarTar''