tycho
tycho copied to clipboard
eclipse-tycho
Move Tycho-Pomless documention from wiki to site
At the moment a lot of documention about Tycho-Pomless resides at this repos wiki at: https://github.com/eclipse-tycho/tycho/wiki/Tycho-Pomless
I think that documentation would be better placed at Tycho's documentation site. That's the place where I would search for it first.
If I understand it correctly a corresponding TychoPomless.md markdown file can be placed at src/site/markdown and will eventually show up at Tycho's Site?
If this is correct the content from the wiki could be (more or less?) simply be copied.
This would also have the advantage that the documentation can be maintained together with the code.
Site documentation is only updated on release, I found it more useful to update some docs also between releases.
You'll have to reference it in https://github.com/eclipse-tycho/tycho/blob/master/src/site/site.xml AFAIU. @laeubi site seems to not have been published last for 2.7.0. Can you publish the 2.7.4 ?
If we want to use more "site" stuff I think publishing should be automated so they are simply published on every build of a tycho-x-branch.
By the way currently this seem to require a gerrit (!) to be created, we maybe better publish it to the github-pages, especially now we have an won tycho org? See https://pages.github.com/ ... this should allow us to fully automate this.
@LorenzoBettini as you have described it here do you think you can help us setting this up for tycho if we create the necessary repository?
Site documentation is only updated on release, I found it more useful to update some docs also between releases.
That's a point.
If we want to use more "site" stuff I think publishing should be automated so they are simply published on every build of a tycho-x-branch.
Sounds very good to me. I also wondered if it would be useful to keep the site of previous releases. At least of some. Maybe only for minors or at least the last one of a major branch. I think those that don't want/can migrate to Tycho 3.0 once it is released would be happy to at least have the documentation available. IIRC I have seen it that there is a drop-down menu next to the version where one can select another version.
Besides the releases (current and some previous?) there could also be a snapshot of the current master so that can can see an update immediately.
I think it should be something like:
- master/
- tycho-2.7.x
- tycho-3.0.x
- ... and so on
We can the use an index file that simply gives a link to the subfolder (unless someone likes to create a page for tycho itself...)
Sounds good, but I cannot help with the website stuff itself. Never done this.
If @mickaelistria and @akurtakov are fine with that, I'll create a ticket with infra to setup the github pages repo tomorrow... that would be the first step.
@LorenzoBettini as you have described it here do you think you can help us setting this up for tycho if we create the necessary repository?
@laeubi yes, with pleasure! But I'm on holiday, I can get back to you approx next week, ok?
@LorenzoBettini as you have described it here do you think you can help us setting this up for tycho if we create the necessary repository?
@laeubi yes, with pleasure! But I'm on holiday, I can get back to you approx next week, ok?
I don't think we are in hurry here, so no problem :-)
Go :)
Here we go https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/issues/1650
@LorenzoBettini the page is setup now! So we are ready to accept a PR whenever you are ready :-)
- Web link: https://eclipse-tycho.github.io/
- Repository: https://github.com/eclipse-tycho/eclipse-tycho.github.io
I would suggest we start with the following:
- There is a
docfolder in the root - for each branch that starts with
tycho-a sitedoc should be generated and placed insidedoc/<branch name> - we have a GH action that is triggered by a push to any
tycho-*branch that publishes the sitedoc from this branch into the folder - we edit the
index.htmlfile to have a link to each subfolder (has to be done manually at the moment), if I understand the github docs correctly we can also use a README.MD if that is more sufficient.
The next steps could then to adjust the sitedocs itself, maybe with a link that says "Looking for another Tycho version?" that reference to the index.html page.
@laeubi, I'm not sure I understand how you want to proceed. My blog post is about publishing a Maven site to GitHub pages, together with plugin documentation. So the actual source repository should be this one.
@LorenzoBettini you can simply push it to https://github.com/eclipse-tycho/eclipse-tycho.github.io master branch instead of the Tycho repository itself.
You can take a look at https://github.com/eclipse-tycho/tycho/blob/master/.github/workflows/verify-platform.yml how to checkout different repositories side-by-side.
@LorenzoBettini if you still think its easier to push it to the same repo, we can still do this and link from the main site to the tycho-project site, so I would laeve the descission to you what is more suitable.
IMO, best is to have "manual" documentation directly in the repo, together with the code (same branch, not in a wiki), in some "documentation" folder. Maintaining a website is more complicated and doesn't bring additional value. As for the automated documentation, how is GitHub a better service than the current eclipse.org site? If there is no additional value to expect, it's probably not worth changing.
IMO, best is to have "manual" documentation directly in the repo, together with the code (same branch, not in a wiki), in some "documentation" folder. Maintaining a website is more complicated and doesn't bring additional value.
The suggestion was to maintain this as part of the site-doc, so we get a website generated automatically.
As for the automated documentation, how is GitHub a better service than the current eclipse.org site? If there is no additional value to expect, it's probably not worth changing.
We can deploy automatically the site-docs by GH action, while currently it requires us to generate the site doc locally, commit to a gerrit repo (no idea what will happen to that in the future ...) open a review, and as far as I can remember only some people can then actually merge this.
I actually challenge even the fact that we need a website at all. The benefits you're pointing would apply to a documentation folder in the master branch as well.
I actually challenge even the fact that we need a website at all.
Do we really want to start defining what "a website" is? Is Github UI a "website"? Beside that, Eclipse projects really would benfit from having a "real" website, just take https://karaf.apache.org/ and then look at the "websites" of usual eclipse projects e.g. Tycho https://projects.eclipse.org/projects/technology.tycho I think yes we
- could really need a website to better explain what tycho is, how to access the docs and examples
- there are many shades of "website"
The benefits you're pointing would apply to a documentation folder in the master branch as well.
Only for people who like reading source codes, see above... all content you can browse on the web is actually a website and I assume we don't want people to checkout the source an look at raw text files instead.
A folder in the source code is really hard to discover, hard to link to and has a bad user experience.
Only for people who like reading source codes, see above...
Isn't it actually our target audience? I used to believe that the project facade was important in the past, did spend some good time trying to polish some project websites, trying to get some good logos and all the thing that feel nice. And now, I'm convinced that all that, for a technical project towards developers such as Tycho, is not worth the effort and is lowest priority, far after 1. reacting to community interactions and 2. improving the code and 3. shipping releases. Particularly as a website is yet-another-artifact to maintain (with processes, builds, technologies that will add up to existing ones we need to manage for the "payload" of the proejct). But I won't veto anything, I just want to emphasize that it's IMO not a good idea, and to kind of get everyone understanding while I will most likely not at all contribute to this effort.
Isn't it actually our target audience?
The target audience are people that need to setup/configure a Tycho build. These might be developers, build managers or whatever, at least people that expect to have up to date documentation in a accessible way without having to ask and given a folder with loosely structured information.
Particularly as a website is yet-another-artifact to maintain
That's why it should be all automated so we can commit code and the rest goes on. and then maybe even others can help with making the "website" more nice, I think @wimjongman has experimented in the past with GH pages generation as well.
Yes, we have the BIRT documentation automated. Just change some markup, PR, merge, and the site is rebuilt.
https://eclipse.org/birt
https://github.com/eclipse/birt-website
@wimjongman that looks really nice! By the way you can:
- get an own org for bird (actually recommended by eclipse infra)
- get an nicer domain e.g. we have https://tycho.eclipseprojects.io/
just open a ticket in the EF gitlab tracker!
Thanks, but we have settled on this. It would be disruptive again for the community.
@wimjongman everything is redirected, so there should be no "disruption" but of course it is your choice :-)
I have now started some work here: https://github.com/eclipse-tycho/tycho/pull/1497
@laeubi sorry, I had forgotten about that... please let me know if you face any problems, and I'll try to help as far as I can.
It seem to work now to generate the sitedoc, but I can't get it to push to another repository in the same organization:
https://github.com/eclipse-tycho/tycho/actions/runs/3218458142/jobs/5262648916