Hello Andreas, On Mar 10, 2010, at 12:28 , Andreas Jellinghaus wrote: > Am Mittwoch 10 März 2010 09:36:34 schrieb Martin Paljak: >> On Mar 10, 2010, at 10:07 , Andreas Jellinghaus wrote: >>> to me your emails read like you want to remove/loose/strip down >>> most information. the result might be small and up-to-date, but >>> it is not acceptable from my point of view to loose all the >>> information in the wikis we have already. >> >> A wiki should have self-organizing capabilites to only show relevant >> information in a useful way and so that it could be easily found. There >> can be (and usually is) a lot of "existing but abandoned" information. > > "self-organizing capabilities"? lets not play buzzword-bingo. It is no BS bingo, I have deployed Trac in commercial settings in real life and seen it work extremely well (especially wikis) for teams sized from 3 to ~75 people. Or just take a random research paper done about Wikipedia content evolution.
>> Looking at the trac contents of engine_pkcs11 and libp11 - seems to be >> mostly a copypaste. > > well, both contain the minimum information needed as software documentation. > lets have a look at the latest tar.gz and the files it contains in doc/ > (engine_pkcs11 in this example): I was talking about wiki content, not the targzip content. I can't remember where and why the decision was done to pump all wiki content to the targzip as official documentation. A look at Ubuntu libengine-pkcs11-openssl package reveals: /usr/share /usr/share/doc /usr/share/doc/engine_pkcs11 /usr/share/doc/engine_pkcs11/README /usr/share/doc/engine_pkcs11/NEWS.gz /usr/share/doc/libengine-pkcs11-openssl /usr/share/doc/libengine-pkcs11-openssl/copyright /usr/share/doc/libengine-pkcs11-openssl/changelog.gz /usr/share/doc/libengine-pkcs11-openssl/NEWS.gz /usr/share/doc/libengine-pkcs11-openssl/changelog.Debian.gz /usr/share/doc-base /usr/share/doc-base/engine-pkcs11 For packages like libp11 and engine_pkcs11 these are the only two files that should be included with a targzip, one describing usage and a link to the webpage and one describing installation instructions. I also suspect that libp11 and engine_pkcs11 only matters most to developers, who usually require other information and look for it on the internet usually. >> Yet Another Trac Instance won't make it better. It should be a well known >> software myth: "or devs have the latest tools, the greatest utilities, >> fastest machines => they should be kickass" when in fact the kickass tools >> are not used. > > what does trac instances have to do with whatever that myth is supposed to > tell me? you lost me. A few years ago, when Trac was set up, there was a good reason for a real requirement: a tracking software is needed. It came in the form of Trac, with wiki and subversion. Several original developers lost motivation for various reasons and time passed. Developers come and go and deal with other things in between (like me). The original idea to a) have a tracking software for some collective release planning and b) extract some components with APIs from opensc to help maintenance ended up with a small infrastructure project instead, with all the components being split into their trac-s. I should have voiced my opinion about this years ago when it happened, but well... The assumption that "giving all small projects their own trac instances will make them well functioning instances in project management sense" is the fail here. That's what I'm trying to improve by collecting them back together (to some extent) The assumption that "trac does not work, lets take a new trac and try to make that one work better than previous ones work" does not work. You can substitute trac with whatever supporting application you want. >> I don't believe that a new trac instance (or a bugzilla) would make >> anything better. > > sure. it gives us a backup, something working we can use, till we see > the new one works and is ready. that is good. > > in fact it would be stupid to remove content from the existing trac > instances, > what would we do if you had to stop your work half way for some reason? > we would have neither the old working nor the new stuff, only shards. Wiki history can be reverted. I have been talking about copying content and eventually directing (HTTP redirecting?) people to a single location. I wrote "moving" because eventually this is the goal: move people to the place with most information. >> OpenSC wiki is overloaded with information that has nothing to do with >> OpenSC. Having more of it can not hurt, especially if it is up to date and >> relevant. >> >> The wiki is not attached to a version. It is live documentation. There is >> no connection between wiki content and a snapshot of it in a versioned >> software tarball, doing it with this understanding would be wrong. >> >> IIRC the reason to bundle wiki docs in the tarball was that there are users >> without live internet connection. Whatever gets in the "offline wiki dump" >> for these people is better than nothing. > > well, a software in .tar.gz form should include a copyright file, instructions > how to compile it and use the software, where to report bugs, and all that. > sorry if I'm old-fashioned, but I think it should be that way. I also like README and INSTALL docs a lot with unix software. Unfortunately many INSTALL files are the default autoconf templates :) A line with "Documentation is available on-line on http://..."; would suffice. Or a well selected and written subset of the wiki docs in HTML format. In real life internet is ubiquitous these days. Software (especially software development) and internet can not be detached. >> The goal is to actually track tickets, not to have a a gazillion of bug >> tracking software instances. Whatever tool that works is better than >> nothing or better than a bunch of tools not being used. OpenSC trac has a >> lot of tickets that represent *something* > > so if people file a ticket in "opensc" trac for "libp11" component, > with a bogus version, as they cannot select the libp11 versoin, that > will be easier than doing the same thing in the "libp11" trac? Uh. There's no versioning information set for libp11. I know it feels a bit awkward maybe, but versions can also be recorded in keywords. In real life a bug with some version of open source software is replied with: Did you try with the latest version? Did the problem go away? Yes - problem solved and nobody cares about the version (as the default answer is always "it is fixed in latest version") No: version does not matter, as the bug is probably present up to the latest version. Eventually what matters is that issues get tracked and eventually fixed and that you don't have to dig through e-mails to know the status of an issue. As developer resources on any of the projects is scarce, it is easier to have a single location to check than 6 or 10 OpenSC, even though a separate piece of software, forms an "open source stack for smart cards" that is viewed as a whole by many non-familiar people (and also functions as a whole) > sorry, but I think your changes - adding the other projects as > components inside opensc wiki - will cause a lot of more confusion > and not help at all. so please revert. > > neither wikis nor control-version-systems nor having root on opensc- > project.org is a replacement for developer communication. if people > tell me I'm wrong we can follow your plan, but please lets discuss > such changes first, and not simply do things. in a wiki a changed > page can be reverted, but reconfiguring opensc ticket system is a > much more invasive change, and should be discussed first. Invasive? You said you consider the whole trac a fail and don't care? > Move was the wrong word. I meant copy. > > ah, ok. > > so what is your plan for the other project? I still think each > project needs to have some minimal user/developer documentation > shipped with them in the tar.gz, so it is available in the distributions. > do you agree? how should that documentation be written and maintained, > if you implement your plan with the new trac/wiki? I proposed docbook > (or some other format) with source code of the documentation inside > the svn, but I don't remember you commenting on that. User documentation in the package should be 1. README file 2. man pages. Evertyhing else should be online. Developer documentation, if any, should be a doxygen API description. A versioned README/INSTALL file is the easiest in many cases. Guides, tutorials, howtos are best left to the web. >> Where does b...@opensc-project.org go? How many e-mails has it received? > > bugs: aj,nils > I can add more people. maybe one email in three months. What has happened to those e-mails? What are the 4 bugs that were reported last year? Cheers, -- Martin Paljak http://martin.paljak.pri.ee +3725156495 _______________________________________________ opensc-devel mailing list opensc-devel@lists.opensc-project.org http://www.opensc-project.org/mailman/listinfo/opensc-devel
