readme and homepage

[antis81]

Seems, that the project info file readme.md got lost during the movement into submodules. Additionally, I think it is worth to present MGV on a homepage providing some screenshots and links to ohloh and github. It is still a long road until v0.1 Genesis, but slowly MGV is getting to a point, where it starts to become somewhat usable ... at least presentable.

[scunz]

Yeah, i tend to agree to all of that. Feel free to cook something up :-)

[antis81]

Created basic homepage here: http://macgitver.github.com/MacGitver

This is an exact copy from the README.md file without modifications by now. Just to have a starting point.

[scunz]

Few comments:

• Shouldn't we be better off using an organization-page (i.e. macgitver.github.com which would then be stored in master of git://github.com/macgitver/macgitver.github.com)?
• Should I redirect macgitver.org there - or should we redirect the other way and host on macgitver.org? This just reminds me that I've missed to reply (acutally, for 3 months) to an answer from the host, telling where the MX-Records should point... sigh
• I think, the screen shots should better be commited to the wiki. And the landing page should point there.
• I'm not sure, whether i got this right: But didn't your manual commits to the gh-pages branch nuke the possibility to update the page from README.md?
• Obviously, jekyll got issues with nested lists. At least in the way they are written in README.md.
• The zip- and .tgz- downloads are broken. kneath of github fame deprecated downloads from the github websphere about one month ago. We never had files hosted, so these links don't point to anything useful. Maybe this is an oversight from the github team: Jekyll produces a link that gets redirected somewhere (different from the "zip"-link in branch-view on gh) and just says "not found". However, this might also be because we don't have a master branch at all

[antis81]

Shouldn't we be better off using an organization-page (i.e. macgitver.github.com which would then be stored in master of git://github.com/macgitver/macgitver.github.com)?

Yes, it's a good idea.

Should I redirect macgitver.org there - or should we redirect the other way and host on macgitver.org? This just reminds me that I've missed to reply (acutally, for 3 months) to an answer from the host, telling where the MX-Records should point... sigh

We can go either way. Right now, I don't want to put a lot of effort in a webpage. It is more easy, using what GH offers too show the key features of MGV and do quick updates. Stability of the server also matters.

I think, the screen shots should better be commited to the wiki. And the landing page should point there.

Sounds good.

I'm not sure, whether i got this right: But didn't your manual commits to the gh-pages branch nuke the possibility to update the page from README.md?

Yes, that's right. Thinking about it, it might even be better to start by setting up links in the README.md, pointing to the wiki.

Obviously, jekyll got issues with nested lists. At least in the way they are written in README.md. The zip- and .tgz- downloads are broken. kneath of github fame deprecated downloads from the github websphere about one month ago. We never had files hosted, so these links don't point to anything useful. Maybe this is an oversight from the github team: Jekyll produces a link that gets redirected somewhere (different from the "zip"-link in branch-view on gh) and just says "not found". However, this might also be because we don't have a master branch at all

You're right. But that's not bothering me too much at the moment, as we don't really have something useful to download yet - like you wrote.

[scunz]

Ok, then, I'm about to setup macgitver.github.com, and update the readme a bit. I'll add it to the access-control last, so you'll directly know when i'm done.

[antis81]

I think we can get rid of the gh-pages branch here in favour to the macgitver.github.com repository, can we?

[scunz]

that was my intention, indeed. Are access rights okay?

[antis81]

Not sure, but that doesn't matter much, right? So if you like just delete the branch or I can do it either :smile:.

[scunz]

I've just done a few extensions to our build system; both to the umbrella builder and the MacGitver root module itself. I've written down a few words on the umbrella builder.

With this change, we have now full cmake based support for generating doxygen documentation. I've set it up to work for libGitWrap and libHeaven. For each, 2 flavours of documentation can be generated: public and internal. While the public one is designed to be read by users of our libraries, the internal one is designed to be read by the people willing to develop those libraries further.

CMake is instructed to generate special build targets for building those docs. make docs will simply generate all flavours. make help shows a summary of all targets, including the new doc-targets.

The internal docs build will only warn about real bugs in documentation source. The public docs will warn about any undocumented function (not classes!). Undocumented classes will simply not show up at all. The warnings use the default Doxygen output format for warnings, which happens to be compatible to GCC/CLang, so QtCreator is able to parse the output nicely.

In QtCreator, when activating the "Projects" mode (ctrl+5), in the make steps category, a list of all build targets is shown. Enabling all and libHeaven_pubdocs allows to do a doxygen run with every build; integrating all the doxygen warnings into the normal development workflow.

libHeaven (uncrappify branch) has currently 106 such warnings, libGitWrap has 248 of them. For libHeaven, I will not merge the uncrappify1 branch before this number reached zero :-) And I actually hope, that it won't ever increase thereafter.

The libGitWrap warnings are mostly due to the fact that almost all classes have a class-documentation, but no member documentations yet. I think, we can only fix that over time. The problem being that contentless documentation is worth nothing more than missing documentation. Or in other words: These warnings are actually eligible. I'm not currently planning on a libGitWrap rewrite as big as the libHeaven one. Without such a rewrite, I wouldn't have bothered to write some libHeaven documentation at all - I can dig 10 times into the code from scratch within the same amount of time required to write good code documentation once.

As a side effect of all this, the layout of the doxygen docs can now fully be customized by anyone having commit access to the mgv repositories - even without leaking the infrastructure used on macgitver.org.

[edit]: Starting with the merge of the uncrappify-branch, I will instruct jenkins to actually build those docs during the 6-hourly integration run and rsync the results over to the web-server's space. Until then, I will only update the libHeaven docs manually.

[antis81]

This is absolutely great stuff :+1: :smile:. And especially for the libHeaven it is a good decision to completely document it, as most of the visible stuff is about it and there's a good chance to bring more contributors in.

[scunz]

Actually, I see both, libGitWrap and libHeaven, as flag-ships. It's more likely that we will get more contributors to either of them than it is likely to get new contributors to MacGitver. Though, libGitWrap will probably be first - libHeaven has still a very very long way to go, before anybody will find it useful.

But this raises a more interesting question: Do we have (or even need) a plan on how to spread word, once we actually do release a MacGitver V0.1?

[antis81]

But this raises a more interesting question: Do we have (or even need) a plan on how to spread word, once we actually do release a MacGitver V0.1?

Yep indeed. I think, what we have urgently needs some polish :smile:. Some thaughts about that:

• The project wiki, homepage and readme.md are a very good start and need to be improved. The readme.md could be part of the homepage and sync'ed using jekyll. It could be used as an "overview" page then, showing just the ready to use features and a small guide on "how to contribute" :wink:.
• Further, I like the idea with the single issue containing a check list of "minor todo's". Maybe each version/milestone could have such a list.
• We need to get more clear about, what to realize in V0.1 (and the affected Module(s)). We could use more labels in issues for that, like "website", "ui", "settings", "usability", ...
• I think, we should move the milestones to the MGV umbrella. It would be great, if we could link to the subprojects in a generic way in GH (similar to ohloh). But that's currently a dream, or is it?

[scunz]

It would be great, if we could link to the subprojects in a generic way in GH (similar to ohloh). But that's currently a dream, or is it?

We could probably setup gh-pages branches in libHeaven and libGitwrap. But I don't think that this is necessary. We could as well extent the doxygen docs to a full blown web page and publish that at libHeaven.MacGitver.org and libGitWrap.MacGitver.org.

a small guide on "how to contribute"

GH does provide special handling for a CONTRIBUTING.md in the root directory. We should setup one and commit that to all our SMs. But what I think that we need more than that, is a definitive guide to compiling MacGitver. I will setup such an .md file. But as we got no place to put it, i'd start with committing it to MacGitver.git's root.

The readme.md could be part of the homepage and sync'ed using jekyll.

If we're going into that direction, we should do it right. We need a jekyll template anyway and for testing a suitable ruby environment. Actually, I have such environments locally and babbelbox.org has it too. I'm not sure about macgitver.org, but I think it has it setup, too. babbelbox.org is running a gitlab instance on ngnix (containing some code i really don't even want to be in private GH repos). macgitver.org runs apache2.

But what we need even more is a design. So, what I'll propose here, is:

• setup a www.macgitver.org repository.
• populate it with .md files.
• create a website design
• bridge the design and the .md files via jekyll
• If we are that far, we no longer require the automatic hosting system for gh-pages, it is actually just one more job in Jenkins to trigger the web-site regeneration then...

Another problem that we still have to deal with is the state of lg2. There is still no support for SSH, which is the most annoying. But there's still no stable-api promise and all features based on merge (merge, cherry-pick, revert, rebase) are still missing.

[antis81]

Phew, lots of text ... Think we can close it in favor to #5