Support switching between Piwik versions #139

tsteur · 2016-08-05T03:07:50Z

fixes #138

Adds a new Piwik selector next to the "search"
By default content is viewed for latest version
When switching to an older version it will prefix all resources with '/2.x', eg '/2.x/guides/....'. The implementation is kind of future proof and it will be easy to add new versions in the future see README.
If a page cannot be found we look if the same resource is available for another Piwik version and on the 404 page suggest matching links
If someone is viewing a guide for an older Piwik version, and the same content is available for a newer version, we add a link at the very top mentioning exactly this.
Currently I mark all content for older Piwik versions as noindex re the duplicated content.
I adjusted the generator to generate the classes for Piwik 2 and Piwik 3
In browser title I added currently eg v2 or v3 eg Piwik Analytics - Developer Docs - v3, could also have Piwik 3 Analytics ... or not mention the version there at all
I have added a new kind of PHP Category that let's us define menus in markdown so we won't need to adjust code when wanting different menu for Piwik 2 and Piwik 3 (this works only for submenus so far).
I have written / updated 6 guides for Settings, Widgets, Reports, Menus, Database updates for Piwik 3 + migration guide from Piwik 2 to 3
Changelog currently points to the changelog defined in 3.x-dev branch. This means we will always need to merge changes from 2.x-dev (currently master) into 3.x-dev. While this may work for two Piwik versions only, it can get harder when there are 4 or 5 different Piwik versions. What we could do for this is to fetch individual changelogs for each Piwik version and have either menu items for different Piwik versions or merge them all into one page. First all changes for latest Piwik version, then all changes for older Piwik versions. Be nice to have maybe now everything on one page, once there is Piwik 4 or 5 a menu item for each Piwik version might be better. The thing is we would need to start a new changelog for Piwik 3 to make this happen. Meaning we remove all declared changes for Piwik 2.X in the Piwik 3 branch otherwise there will be likely duplicated content and the changelog would be "wrong" anyway because if we ever don't merge changes for changelog from 2.x into 3.x it would not show all changes obviously. Especially when there is Piwik 4 or 5 it would not be manageable anymore to merge all changes into one changelog file.

So far, docs can be put into docs/2.x, docs/3.x and directly under docs/. If eg a guide is requested for Piwik 2, we first look for docs in docs/2.x and if not found for docs in docs/. This allows us to have some pages always the same, eg support page etc. So far I have left all guides under docs/ as not many docs will actually change for Piwik 3. This way, when changing a document under docs/ it will be updated for Piwik 2 and 3.

As soon as something on a guide changes for Piwik 3, we should copy that article into docs/2.x and afterwards make adjustments on the content for Piwik 3. As soon as we release Piwik 4 it gets a bit more complicated but we can think about it when this actually happens. We would under circumstances need to copy the article into docs/2.x and docs/3.x as soon as we need to change an article for Piwik 4 (or we implement some logic that checks for different Piwik directories but that wouldn't be as good likely and not important for now). I think we just need to see how it goes and change behaviour if needed. I have also explained this in README.md.

The main problem are links to other pages and menu items. Say an article links to a class in Piwik 3 but this class doesn't exist in Piwik 2, then the guide that is the same under Piwik 2 and 3 is broken and we would not to put that guide into the docs/2.x page and adjust the link there. It can get quite complicated to notice and to decide when an article needs to be copied into docs/2.x folder. We could therefore also copy pretty much all pages into docs/2.x this way they would be always the same and we wouldn't need to care about anything when changing it (apart from pages like "Support", "Piwik Core Development", ... which should always be the same). This would be the safest way but some pages would not be updated automatically when eg fixing a guide in Piwik 3.

Might be better to discuss how to handle it in person and we can change it any time

We also need to find a solution for images used in guides. Some guide link to images from piwik.org such as http://piwik.org/wp-content/uploads/2014/09/action_example.png . We should probably make sure to have all images in this repository and have different versions of it such as img/2.x/ and img/3.x/

… version, specify menus as much as possible in markdown

… version

mattab · 2016-08-15T02:14:10Z

Currently I mark all content for older Piwik versions as noindex re the duplicated content.

The downside of using "noindex" for older content is that, pages that used to exist but don't exist anymore, will not be indexed by search engines. Maybe it would be useful to have these old pages still indexed?

While this may work for two Piwik versions only, it can get harder when there are 4 or 5 different Piwik versions. What we could do for this is [...]

when there will be 4 or 5 versions, there will still be only two at most that are "actively worked on" (LTS + current), and may have their changelogs updated. as there will be at most the LTS changelog to merge into the "latest" developer changelog, your current simple solution looks good!

It can get quite complicated to notice and to decide when an article needs to be copied into docs/2.x folder. We could therefore also copy pretty much all pages into docs/2.x this way they would be always the same and we wouldn't need to care about anything when changing it [...] This would be the safest way but some pages would not be updated automatically when eg fixing a guide in Piwik 3.

The "safest way" seems the best solution for us.

(apart from pages like "Support", "Piwik Core Development", ... which should always be the same).

Does it mean these pages should not be copied? or will the website know which pages should always be the same and it doesn't matter whether they are copied or not?

We also need to find a solution for images used in guides. Some guide link to images from piwik.org such as http://piwik.org/wp-content/uploads/2014/09/action_example.png . We should probably make sure to have all images in this repository and have different versions of it such as img/2.x/ and img/3.x/

So is the solution to include all our guides' images currently loaded externally into our img/ folder?

I'll take a look at the code now

mattab · 2016-08-15T02:17:24Z

app/routes/page.php

@@ -153,11 +209,12 @@ function renderGuide(Slim $app, Guide $guide, Category $category)
    }

    if ($fetchContent) {
-        $markdown = file_get_contents('https://raw.githubusercontent.com/piwik/piwik/master/CHANGELOG.md');
+        $markdown = file_get_contents('https://raw.githubusercontent.com/piwik/piwik/3.x-dev/CHANGELOG.md');


Could this URL be constructed dynamically reusing the constant LATEST_PIWIK_DOCS_VERSION maybe?

We can do this once we have develop branch for 2.X etc. It's a bit problematic currently to do this automatically since we will make 3.x to master at some point and then we can change it but we basically never know to which version master points so it can be only kind of automated a bit later

good point!

tsteur · 2016-08-15T02:54:11Z

when there will be 4 or 5 versions, there will still be only two at most that are "actively worked on" (LTS + current), and may have their changelogs updated. as there will be at most the LTS changelog to merge into the "latest" developer changelog, your current simple solution looks good!

Just to be clear. This means whenever we make a change to an older changelog we need to immediately merge this into master or the latest piwik version with all the changes. It's already outdated at the moment and only works if we don't really maintain LTS versions

tsteur · 2016-08-15T02:55:36Z

So is the solution to include all our guides' images currently loaded externally into our img/ folder?

Yes

Does it mean these pages should not be copied? or will the website know which pages should always be the same and it doesn't matter whether they are copied or not?

We should leave some of the pages under docs/ directly so they will be the same across all Piwik versions "forever".

tsteur · 2016-08-15T03:52:54Z

It now shows canonical for 2.x if the same content exists for 3.x and I have duplicated all docs into 2.x apart from 3 that remain under /docs

follows up fda46f1 refs matomo-org/developer-documentation#139

mattab · 2016-08-15T05:11:08Z

Awesome PR!

made some minor updates in 1517f6a

Feel free to rebase + merge 👍

tsteur · 2016-08-15T05:52:18Z

docs/2.x/migrate-piwik-2-to-3.md

@@ -1,235 +0,0 @@
---


FYI: We cannot simply remove documents as they are referenced in the menu. We need then to also adjust the linking document which I did just here: 7727baf#diff-42780b1e896c88c6ac34a0e8cab1fcabL2 . Basically I removed it from that submenu and because there is no submenu left I have also removed the title so the category "Migration" won't appear for Piwik 2.x at all.

tsteur · 2016-08-15T20:52:05Z

deployed :)

tsteur · 2016-08-15T21:25:23Z

FYI: We will also need to be careful when adding links to github. Ideally we start always working on a X.X branch and send the links eg to "2.x-dev" branch or "3.x-dev" branch. This way we make sure the links will still work when eg merging 3.x-dev into master

tsteur added the enhancement label Aug 5, 2016

tsteur added this to the Current sprint milestone Aug 5, 2016

tsteur and others added 24 commits August 11, 2016 05:33

starting to add a piwik version selector into the header

407a0fd

keep files by default in docs root unless they are different in older…

e02e9cb

… version, specify menus as much as possible in markdown

first new guide for piwik 3

83fa3c9

more docs

eef66a6

new widgets docs

456f822

updated menu doc

4cee0f1

save piwik version in the URL

0764a7e

in 404 pages show a link if document is available for different piwik…

566401d

… version

bugfixes and added docs

77b4d16

updated docs

db2f9f1

updated docs

9c33a4d

new reports guide

7f6c587

another doc for piwik 3

dc0afe3

started to add a migration guide

c9a9756

versioned images, changelog points to Piwik 3, other fixes

54831ff

fix detection of api tag

cfc895d

documented new rendertemplate method

d5272c9

it is not needed to check for permissions twice

f5abfd0

show version in title

9a45c25

document how to manage plugin json

aa31021

use canonical tag if version is available in newer version

8ba7982

copy content into Piwik 3 and old content into Piwik 2

fbbccfc

Minor changes in the new developer guides

b9dfeb4

skip menu items if no title is specified

fcabb40

mattab reviewed Aug 15, 2016
View reviewed changes

mattab mentioned this pull request Aug 15, 2016

Release Piwik 3.0.0-b1 matomo-org/matomo#8836

Closed

8 tasks

mattab added a commit to matomo-org/matomo that referenced this pull request Aug 15, 2016

Plugin updates are located within the \Updates namespace

49987b0

follows up fda46f1 refs matomo-org/developer-documentation#139

mattab mentioned this pull request Aug 15, 2016

Plugin updates are located within the \Updates namespace matomo-org/matomo#10398

Closed

3 tasks

tsteur reviewed Aug 15, 2016
View reviewed changes

tsteur force-pushed the piwik3 branch from 7727baf to fcabb40 Compare August 15, 2016 20:05

tsteur merged commit 1cb64e8 into master Aug 15, 2016

tsteur deleted the piwik3 branch August 15, 2016 20:52

Findus23 mentioned this pull request May 7, 2020

more deprecated 2.x docs #344

Merged

innocraft-automation removed this from the Current sprint milestone Jan 20, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Support switching between Piwik versions #139

Support switching between Piwik versions #139

Uh oh!

tsteur commented Aug 5, 2016 •

edited

Loading

Uh oh!

mattab commented Aug 15, 2016

Uh oh!

mattab Aug 15, 2016

Uh oh!

tsteur Aug 15, 2016

Uh oh!

mattab Aug 15, 2016

Uh oh!

tsteur commented Aug 15, 2016

Uh oh!

tsteur commented Aug 15, 2016

Uh oh!

tsteur commented Aug 15, 2016

Uh oh!

mattab commented Aug 15, 2016

Uh oh!

tsteur Aug 15, 2016

Uh oh!

tsteur commented Aug 15, 2016

Uh oh!

tsteur commented Aug 15, 2016

Uh oh!

Uh oh!

Support switching between Piwik versions #139

Support switching between Piwik versions #139

Uh oh!

Conversation

tsteur commented Aug 5, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mattab commented Aug 15, 2016

Uh oh!

mattab Aug 15, 2016

Choose a reason for hiding this comment

Uh oh!

tsteur Aug 15, 2016

Choose a reason for hiding this comment

Uh oh!

mattab Aug 15, 2016

Choose a reason for hiding this comment

Uh oh!

tsteur commented Aug 15, 2016

Uh oh!

tsteur commented Aug 15, 2016

Uh oh!

tsteur commented Aug 15, 2016

Uh oh!

mattab commented Aug 15, 2016

Uh oh!

tsteur Aug 15, 2016

Choose a reason for hiding this comment

Uh oh!

tsteur commented Aug 15, 2016

Uh oh!

tsteur commented Aug 15, 2016

Uh oh!

Uh oh!

tsteur commented Aug 5, 2016 •

edited

Loading