Migrate wiki to github

[xizhao]

It would nice to be able to contribute edits to a wiki on github as well. i.e. creating an entry on building nomos on mac:

brew update
brew install glib

Then edit makefile.conf to append brew's include path to glib as a CFLAG:

-I/usr/local/Cellar/glib/2.42.0/include/glib-2.0/

[yaobinshi]

I filed a issue http://www.fossology.org/issues/8001 for your suggestion
we will follow up this issue. thanks for your testing and contribution.

[bobgob]

Why do you want more than one wiki?

Bob Gobeille

On Nov 13, 2014, at 7:30 PM, xizhao notifications@github.com wrote:

It would nice to be able to contribute edits to a wiki on github as well. i.e. creating an entry on building nomos on mac:

brew update
brew install glib

Then edit makefile.conf to append brew's include path to glib as a CFLAG:

-I/usr/local/Cellar/glib/2.42.0/include/glib-2.0/

—
Reply to this email directly or view it on GitHub #15.

[xizhao]

I feel like if the codebase is now migrating to github, other things should be centralized around here too. Migrating doesn't mean have two wikis, but instead considering moving to Github as a home for the new wiki. GH has some great collaborative wiki editing features as well.

[bobgob]

Yes, it would be nice to have everything (or as much as possible) on github. But this takes work to move all our docs (need volunteers). Also, the issue tracker on GH is very primitive compared to what we have on fossology.org http://fossology.org/.

Bob Gobeille

On Nov 14, 2014, at 10:29 AM, xizhao notifications@github.com wrote:

I feel like if the codebase is now migrating to github, other things should be centralized around here too. Migrating doesn't mean have two wikis, but instead considering moving to Github as a home for the new wiki. GH has some great collaborative wiki editing features as well.

—
Reply to this email directly or view it on GitHub #15 (comment).

[xizhao]

I am happy to help with these efforts if you add me to the repository. I really like github's ability to reference issues in discussions; but the backlog is indeed very substantial on your JIRA. For now I'd say the wiki is more public-facing so probably would have a higher priority over issues; and while we migrate we can mirror issues manually.

[bufferoverflow]

I'm a fan of README.md files within source tree, this brings docs and code close together.
A specific change can modify code and update the documentation with one commit or pull request.

[bobgob]

Before moving our wiki to github, we need to figure out what content is going to be where. The issue tracker in GH is poor. So I'd like to leave that at fossology.org. We also have nightly builds and release packages and source on fossology.org. And we have our master postgresql schema there. So what stays on fossology.org and what moves to github?

[xizhao]

Would it make sense starting w/ exclusively the developer docs?

[bobgob]

Pros:

• Developer docs next to the code on GH
• Centralize PR & issues around GH community
• Issue tracking, discussion and referencing features
• A specific change can modify code and update the documentation with one commit or pull request

Cons:

• Two different wiki syntaxes.
• Developers will be switching sites for docs.

Please help add to the above pros/cons.

[bobgob]

I should have been more specific with the Pros. In addition to "Developer docs next to the code", I should have included bufferoverflow's "A specific change can modify code and update the documentation with one commit or pull request."

I think xizhao may be right about moving the entire wiki to GH, starting with the developer docs. I'd just like to have more pros/cons laid out.

[bobgob]

The more I look at GH's issue tracker, the more I think that it isn't as bad as my initial impression. Perhaps we can move most of the docs and issue tracker to GH. GH isn't very end user friendly so this would leave fossology.org with just the basics (who we are, how to download, package repos, postgres master schema, ...).

[xizhao]

@bobgob I'd say more users will have an easier time using GH's issue tracker. I think it's pretty straightforward, and you have millions of developers on the site daily using it to track everything. What's great is its ability to reference different issues and commits inline, making discussion a lot easier. For instance if I reference an issue here, a link will show up both here and in that other issue. Most common issue tracking features are there too.

Edit: I just realized you were talking about the average non-developer user browsing fossology.org. I agree; shall we start the move?

[bobgob]

Since we haven't gotten any more comments, I think we can start the move. There are 331 open issues on fossology.org (redmine). Do you want to start there?

[xizhao]

@bobgob Let me create a new issue for the issues, and then assign this one as the wiki docs. For now shall we track all new issues on github?

[xizhao]

Wiki progress: https://github.com/fossology/fossology/wiki

[pguttmann]

I don't seem to be able to create new wiki pages here to assist in this migration :(

[pguttmann]

OK - I just discovered my invitation to join the Fossology group and now have "access" :)

[bufferoverflow]

I think...

• We should keep the "old" wiki as archive and put it in read-only mode.
• Add most relevant stuff to CONTRIBUTING.md, README.md) and co within the source tree
• delete old unused information from wiki's and focus on the source tree

best!
-roger

[silverhook]

Is it still the plan to migrate and consolidate the documentation onto GitHub Wiki as stated in this bug and bug #97?

If so, I would be interested to help out a bit.

[bobgob]

Hello Matija,

I am no longer involved with FOSSology but if no one replies, you could contact michael.c.jaeger@siemens.com mailto:michael.c.jaeger@siemens.com. Michael has been running the project since I left a year ago.

Good luck,
Bob Gobeille

On Oct 17, 2016, at 8:52 AM, Matija Šuklje notifications@github.com wrote:

Is it still the plan to migrate and consolidate the documentation onto GitHub Wiki as stated in this bug and bug #97 #97?

If so, I would be interested to help out a bit with.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub #15 (comment), or mute the thread https://github.com/notifications/unsubscribe-auth/AHr-GjEpt-FWecAxhGwc8OTIvTt4GRLrks5q04u1gaJpZM4C7AdQ.

[silverhook]

Dear Bob,

I realise that @mcjaeger took over the project about a year ago (sad to see you go, BTW). This is exactly why I’m asking if this is still the plan.

Currently the documentation seems to be scattered around a bit and I would be be willing to help clean it up.

[mcjaeger]

Oh, actually good practice that you wrote. Problem with the git hub wiki is that most of the redmine content is impossible to migrate to the github so this stuck, but if you look at the wiki f the github project pages, most of the content is there.
We have had the idea for the installation / administration / user content to go to wiki.fossology.org.

[silverhook]

Right, so the idea is now to (eventually) move all relevant documentation to http://wiki.fossolog.org (DokuWiki)?

[kestewart]

Hi Matija,    Your help is most welcome.   Michael and others have been moving the developer documentation to github along with the code, but the user documentation (how to install it, use it, etc. ) could definitely use some help. 
see: https://wiki.fossology.org/  Which is where there's currrent talk of centralizing it.
Kate 

On Monday, October 17, 2016 10:36 AM, Matija Šuklje <notifications@github.com> wrote:

Dear Bob,I realise that @mcjaeger took over the project about a year ago (sad to see you go, BTW). This is exactly why I’m asking if this is still the plan.Currently the documentation seems to be scattered around a bit and I would be be willing to help clean it up.—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the thread.

[silverhook]

Thanks @kestewart, I’ll look into it :)

[mcjaeger]

please consider also that the main issue with the migration was not so much which wiki, but that tables like

http://archive15.fossology.org/projects/fossology/wiki/Nomos_Test_Cases

Do not go well into the wiki of github. Actually the wiki of integration test case descriptions is the worst issue I have with the migration.

I haven't looked into a markup converter from redmine to docuwiki (wiki.fossology.org) or markdown (github), maybe that could be of great help here.

[silverhook]

For simple tables, it should be pretty easy:

You can get this:

Left align	Right align	Center align
This	This	This
column	column	column
will	will	will
be	be	be
left	right	center
aligned	aligned	aligned

with this code:

| Left align | Right align | Center align |
|:-----------|------------:|:------------:|
| This       |        This |     This     
| column     |      column |    column    
| will       |        will |     will     
| be         |          be |      be      
| left       |       right |    center    
| aligned    |     aligned |   aligned

MarkDown is limited (as any simplistic markup), but the table extension is not uncommon and you can also just dump raw HTML into it if needed.

For converting, I usually first look if Pandoc can handle it – and both Textile and Markdown are covered (unsure about the tables, but those are similar enough in both).

[mcjaeger]

ehem, allright, I got this. The point is to do the conversion of table manually.

[silverhook]

Ah, OK. Well the Markdown and Textile table markups are similar enough that it shouldn’t be too difficult to move. I can do that, if I learn where to put it :)

[mcjaeger]

Hi, I think the safest would be
at http://archive15.fossology.org/projects/fossology/wiki the section "FOSSology Administrator Documentation"
to https://wiki.fossology.org/ into the corresponding section.
I have started the test thing already with the integration test table overview. so there is no double work so far.

[silverhook]

If I understood the discussion on the mailing list and conf call correctly the plan is now to migrate from https://wiki.fossology.org to the GitHub wiki.

I’m moving this to the project board established for that now.

If anyone wants to help out, feel free to check out the Cleaning up Documentation project. First order of business is to label all existing issues as “documentation” and to gather all the pages that are ripe for merging and removal into the #1364.