[SMW-devel] SMW 1.9 entering beta stage
Hey all, Semantic MediaWiki 1.9 is now entering the beta stage, in preparation of the actual release somewhere next month. During this period we will mainly be working on making this already awesome release even more shiny, and making sure everything works as expected. No big new features will be added, and no compatibility changes will be made. Now is the time to try out SMW 1.9 on your test system, and to tell us about any issues you run in to that could prevent you from upgrading to this new release. You can get the code via git, by either getting the master branch, or the 1.9beta1 tag. Alternatively you can get one of the tarballs: * https://github.com/SemanticMediaWiki/SemanticMediaWiki/archive/master.tar.gz * https://github.com/SemanticMediaWiki/SemanticMediaWiki/archive/1.9beta1.tar.gz Preliminary release notes can be found at https://github.com/SemanticMediaWiki/SemanticMediaWiki/blob/master/RELEASE-NOTES-1.9 Cheers -- Jeroen De Dauw http://www.bn2vs.com Don't panic. Don't be evil. ~=[,,_,,]:3 -- -- November Webinars for C, C++, Fortran Developers Accelerate application performance with scalable programming models. Explore techniques for threading, error checking, porting, and tuning. Get the most from the latest Intel processors and coprocessors. See abstracts and register http://pubads.g.doubleclick.net/gampad/clk?id=60136231iu=/4140/ostg.clktrk___ Semediawiki-devel mailing list Semediawiki-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/semediawiki-devel
[SMW-devel] RFC: Technical documentation, installation instructions and release notes
Hey, We have been both shipping documentation together with the source code (as text files) and providing it on the SMW wiki since I joined the project. I see some problems with this. If the documentation is at both places, it doubles the maintenance effort. Given we have quite little resources to spend on this already, this does not help the quality of the documentation in question. Looking at the docs bundled with the source code, it seems that a lot of it is quite out of date, incomplete and sometimes plain wrong. A more focused effort seems to be in order. I propose that for the following items are only bundled with the source code and not duplicated elsewhere: * Release notes * Core installation instructions * Technical documentation on our APIs (and no, I' not talking just about our web API) If this is bundled with the source code, we can keep it fully up to date the whole time. If someone adds a new feature, they should also update the release notes. If someone changes an API, they should update the documentation. Relevant buzzword: Agile documentation. Another advantage comes from the documentation not just being up to date with the latest development, it's also always correct for the version of the code you have. So if you get the previous release, you'll have the correct documentation for it, rather then something that reflects all the development that happened since. Yet another plus of having this together with the source is that people are not forced to hit our wiki. Offline use is possible. And it's just nice to have this in git together with the code, so no additional infrastructure is needed or relied upon. The SMW wiki would not contain a copy of this documentation. It can refer to it, and it can expand on it. Or provide translations. Technical tutorials, full installation guides and so on would also remain on the SMW wiki. What needs to happen to get there? We already made most of the change, just not explicitly. The biggest violators of this policy where the release notes, and our API documentation. The release notes for 1.8 where actually already referenced from the SMW wiki at some point, by embedding the contents of the file from our git repo in the wiki page [0]. And we now have some documentation on our APIs in the docs folder, written in markdown format. Making such a change more explicit means that it is clear the documentation bundled with the source should be updated timeline. It also makes it clear no effort should be spend in duplicating it on wiki. I've been following such a practice myself for several other projects and am quite happy with it. Examples: * https://github.com/wikimedia/mediawiki-extensions-SubPageList * https://github.com/wikimedia/mediawiki-extensions-Diff Feedback is welcome. [0] This is no longer the case as this broke due to WMF breaking the URLs via which our source could be accessed. That has been resolved in the meantime, so we can use this model again for the 1.9 release notes. Cheers -- Jeroen De Dauw http://www.bn2vs.com Don't panic. Don't be evil. ~=[,,_,,]:3 -- -- November Webinars for C, C++, Fortran Developers Accelerate application performance with scalable programming models. Explore techniques for threading, error checking, porting, and tuning. Get the most from the latest Intel processors and coprocessors. See abstracts and register http://pubads.g.doubleclick.net/gampad/clk?id=60136231iu=/4140/ostg.clktrk___ Semediawiki-devel mailing list Semediawiki-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/semediawiki-devel
Re: [SMW-devel] RFC: Technical documentation, installation instructions and release notes
Hi, +1 When I started re-factoring classes and objects, I first thought that the SMW wiki would be the right place for keeping track of such effort but it soon became apparent that maintaining such information on-wiki is not worth energy and therefore I retreated from the wiki as technical documentation source and instead started to use the /docs/ for document that is directly linked to code it represents. Cheers On 11/5/13, Jeroen De Dauw jeroended...@gmail.com wrote: Hey, We have been both shipping documentation together with the source code (as text files) and providing it on the SMW wiki since I joined the project. I see some problems with this. If the documentation is at both places, it doubles the maintenance effort. Given we have quite little resources to spend on this already, this does not help the quality of the documentation in question. Looking at the docs bundled with the source code, it seems that a lot of it is quite out of date, incomplete and sometimes plain wrong. A more focused effort seems to be in order. I propose that for the following items are only bundled with the source code and not duplicated elsewhere: * Release notes * Core installation instructions * Technical documentation on our APIs (and no, I' not talking just about our web API) If this is bundled with the source code, we can keep it fully up to date the whole time. If someone adds a new feature, they should also update the release notes. If someone changes an API, they should update the documentation. Relevant buzzword: Agile documentation. Another advantage comes from the documentation not just being up to date with the latest development, it's also always correct for the version of the code you have. So if you get the previous release, you'll have the correct documentation for it, rather then something that reflects all the development that happened since. Yet another plus of having this together with the source is that people are not forced to hit our wiki. Offline use is possible. And it's just nice to have this in git together with the code, so no additional infrastructure is needed or relied upon. The SMW wiki would not contain a copy of this documentation. It can refer to it, and it can expand on it. Or provide translations. Technical tutorials, full installation guides and so on would also remain on the SMW wiki. What needs to happen to get there? We already made most of the change, just not explicitly. The biggest violators of this policy where the release notes, and our API documentation. The release notes for 1.8 where actually already referenced from the SMW wiki at some point, by embedding the contents of the file from our git repo in the wiki page [0]. And we now have some documentation on our APIs in the docs folder, written in markdown format. Making such a change more explicit means that it is clear the documentation bundled with the source should be updated timeline. It also makes it clear no effort should be spend in duplicating it on wiki. I've been following such a practice myself for several other projects and am quite happy with it. Examples: * https://github.com/wikimedia/mediawiki-extensions-SubPageList * https://github.com/wikimedia/mediawiki-extensions-Diff Feedback is welcome. [0] This is no longer the case as this broke due to WMF breaking the URLs via which our source could be accessed. That has been resolved in the meantime, so we can use this model again for the 1.9 release notes. Cheers -- Jeroen De Dauw http://www.bn2vs.com Don't panic. Don't be evil. ~=[,,_,,]:3 -- -- November Webinars for C, C++, Fortran Developers Accelerate application performance with scalable programming models. Explore techniques for threading, error checking, porting, and tuning. Get the most from the latest Intel processors and coprocessors. See abstracts and register http://pubads.g.doubleclick.net/gampad/clk?id=60136231iu=/4140/ostg.clktrk ___ Semediawiki-devel mailing list Semediawiki-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/semediawiki-devel
Re: [SMW-devel] RFC: Technical documentation, installation instructions and release notes
Hi Jeroen, different answers for different questions: +1 to have detailed release notes in the source code (and nowhere else). The wiki will always have news items and SMW version pages that describe the main changes in a release; the release note file in the source can be linked from the wiki whenever more details are needed. -1 to removing installation notes from the wiki. This is where many users are looking for them. When I did releases, I copied the installation instructions from the source code to a new wiki page, and this was almost no extra work (most work was writing these instructions in plain text first, since it is a bit cumbersome to do this without markup). The real problem that you describe is that the installation notes in the source code do not always get updated properly. This needs to be the responsibility of whoever does the release. It is hard to do this in a very agile way with many developers, for several reasons: * a proper installation manual has a lot of text and some layout, which not every developer can be bothered with * the instructions often depend on many interconnected changes, so it is often not so clear who is in charge to write a change (and it is easy to pretend that one is not) * the instructions include things like version compatibility that are hard to fit into our own development process (for example, if MW releases a new version, then we need to say that we support it; but this is triggered by a change outside of our own code) * installation notes need to include (released) version numbers of dependencies, while master could refer to git branches/revisions of other extensions instead If you want, we could strip down the notes in git to a bare minimum and refer to a wiki page for the final details. This might make it easier for developers to keep the notes updated without getting into extnsive user documentation writing. +0 to keep API documentation in the source. Most things are better documented in the source, the Web API is self-documenting, and the phpdocs should be better than wiki for code documentation. However, some general entry points and high-level introductions to these features and resources should be in the wiki, so people know where to go. However, hooks (=strings in some PHP function) do not appear in the source docs or API docs in a natural way; they might be better documented on the wiki, like MW does it. Cheers, Markus On 05/11/13 09:57, Jeroen De Dauw wrote: Hey, We have been both shipping documentation together with the source code (as text files) and providing it on the SMW wiki since I joined the project. I see some problems with this. If the documentation is at both places, it doubles the maintenance effort. Given we have quite little resources to spend on this already, this does not help the quality of the documentation in question. Looking at the docs bundled with the source code, it seems that a lot of it is quite out of date, incomplete and sometimes plain wrong. A more focused effort seems to be in order. I propose that for the following items are only bundled with the source code and not duplicated elsewhere: * Release notes * Core installation instructions * Technical documentation on our APIs (and no, I' not talking just about our web API) If this is bundled with the source code, we can keep it fully up to date the whole time. If someone adds a new feature, they should also update the release notes. If someone changes an API, they should update the documentation. Relevant buzzword: Agile documentation. Another advantage comes from the documentation not just being up to date with the latest development, it's also always correct for the version of the code you have. So if you get the previous release, you'll have the correct documentation for it, rather then something that reflects all the development that happened since. Yet another plus of having this together with the source is that people are not forced to hit our wiki. Offline use is possible. And it's just nice to have this in git together with the code, so no additional infrastructure is needed or relied upon. The SMW wiki would not contain a copy of this documentation. It can refer to it, and it can expand on it. Or provide translations. Technical tutorials, full installation guides and so on would also remain on the SMW wiki. What needs to happen to get there? We already made most of the change, just not explicitly. The biggest violators of this policy where the release notes, and our API documentation. The release notes for 1.8 where actually already referenced from the SMW wiki at some point, by embedding the contents of the file from our git repo in the wiki page [0]. And we now have some documentation on our APIs in the docs folder, written in markdown format. Making such a change more explicit means that it is clear the documentation bundled with the source should be updated
[SMW-devel] SMW Seattle meetup group formed
Hello, here in Seattle USA I have started http://www.meetup.com/Semantic-MediaWiki Since I dilly-dallied, Meetup.com sent me a 50% coupon. Try it in your town! cheers/jmc On 10/31/2013 5:31 AM, Samuel Lampa wrote: Dear all, Thanks for a super-great SMWCon! It provided lots of inspiration to continue pursuing and promoting SMW for fun and profit, but foremost, it was great to meet all of you in person again (and some for the first time)! :) As you might have heard at the very end of the last day, the first SMW meetup.com group was formed during the conf as well, so I just wanted to invite any Swedes (or Swede-wannabes) to come and join the group: http://meetup.com/smwsthlm (And surely, there will soon be local meetup groups in many more cities :) ) We'll try to make a wider announcement in other channels as well later, but it would be nice to have at least a few SMW:ers in the group to start with, so as not to scare off newcomers :) Cheers // Samuel -- November Webinars for C, C++, Fortran Developers Accelerate application performance with scalable programming models. Explore techniques for threading, error checking, porting, and tuning. Get the most from the latest Intel processors and coprocessors. See abstracts and register http://pubads.g.doubleclick.net/gampad/clk?id=60136231iu=/4140/ostg.clktrk ___ Semediawiki-devel mailing list Semediawiki-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/semediawiki-devel
