Sorry I've missed these discussions, was in transit to england (a good 26 hour trip), and then have been busy with conference stuff and attempting to get my comptuer fixed. I like the ideas here though, I do think we should move to a more constant api, and I think the suggestion of emailing the changes in english is a good one, since the overhead of diving into the java code can be a bit high.
My other thought has always been that any api change should be a minor release, and we should be putting them out more often. That way we don't look like a project that just has an unstable api, we're just one that releases new things quickly. We should have changelogs for each minor version detailing the methods that changed and why - in short the english email that should go out. Any developer who is comfortable with 2.1 say can just look at the list of api changes for 2.6, and know what to do. I think we should even do minor releases for things other than major api changes - indeed we should do less major api changes, perhaps consider calling the feature model merge geotools 3 if it is different enough (not sure I really advocate that, but throwing the idea out there). Like I think Martin's new release is different enough, with the splitting out of referencing into its own module, to warrant a 2.2. C On Tue, 27 Sep 2005, David Zwiers wrote: > I'm in about the same boat as Ian ... I just don't update from trunk until I > need to commit. I really do like the idea of point 1 ... but this is alot of > work too (practicality kicks in). I would be inclined to help / push point > one, but only if we points 4 and 5 are also incorporated. I really do like > the idea of keeping a fairly constant API. We end up costing ourselves > potential users due to our frequent api changes, but we also cost our > current users in terms of developement cycles to update the interfaces. > I am a fan of creating / adopting a set of interfaces ... and with that a > (relatively) formal change request method for the associated interface > definition changes. With the speed (and ease) of API changes, tasks 2,3 are > nearly imposible. I think we should take a look back, and re-evaluate > whether this many changes are necessary, and for those that are, what > process(s) we want to apply. I realize we currently have a code review > process ... but we never get the actual proposed changes written in an > email, as simple english. > My preference for API changes is to see a list of additions (in english), a > list of subtractions (english) and a prototype (java). This would allow > people to ask pointed question about new methods, breaking backwards > compatibility, and ease of use (consequently ... people would have to think > of these themselves, and hopefully explain then in the english sections). > This process would ensure adequate documentation for the javadoc comment, as > the discussion ensued should provide either examples or descriptions that > can be copied from the email into the javadocs (developer bonus here). > A few of my thoughts ... > David > > On 9/27/05, Matthias Basler <[EMAIL PROTECTED]> wrote: > > > > Hi developers, > > > > I took from yesterday's IRC that there had been a discussion about the > > documentation and user/developer distinction and the question why lots of > > projects like uDig do not "use" Geotools as intended (or develop on the > > GeoTools codebase) but just take some bits of it and replace the rest with > > own > > code - and I can include myself here as well. > > > > I've though a lot about where I believe the problems are and how to help. > > Here > > is what I've concluded: > > > > 1. Documentation and release policy > > ----------------------------------- > > I believe what GeoTools lacks is a strict policy that states that a dot > > release > > (such as 2.1, 2.2.) can only be released if it is ensures that all code to > > be > > released is documented > > - in JavaDoc (and I do NOT mean just placeholder stubs as often in > > uDig...) > > - in a/the tutorial and the code snippets > > > > The ideal solution would be: > > 1. A Beta goes out - API freeze > > 2. After this only bug fixing, JavaDoc writing and documentation writing > > (plus localization/installer updates in uDig case) are done > > 3. Release candidates when all three are done > > Checking of integrity (and additionally in uDig case testing > > the localization, installation procedures etc.) > > 3. Final x.x release all this three are done. > > > > I know that several people have tight deadlines (see point 4), but the > > above > > strict policy would avoid lots of problems, from my experience. So I > > believe > > it's worth it. > > > > 2. Up to date tutorials > > ----------------------- > > There was the idea yesterday (I believe by James?) that for each dot > > release the > > state of the tutorial should be frozen. This goes hand in hand with point > > 1: > > Just before the release and AFTER the tutorials have been updated to > > reflect > > the latest changes, a snapshot is done, ideally converted to some nice PDF > > "all > > in one" tutorial/manual and added to the release. > > Any updates then go into the documentation "trunk", whereas the snapshot > > for the > > last official release should be separatly available to the users as the > > "current > > offical version". > > > > Especially in the case of GeoTools - a quickly changing API - I consider > > it > > absolutely vital to have both a "stable release" and a "stable release > > documentation", both of which stay up to date (from a user's point) until > > the > > next official release is done. > > > > 3. Presentation of tutorials and code snippets > > ---------------------------------------------- > > In the meantime the tutorials / code snippets section contains lots of > > pieces of > > the big puzzle. (So I am not complaining about too few documentation in > > general.) > > However the way how this documentation is presented to the user could get > > improved imho. Specifically I miss some real "walkthrough" that takes the > > absolute beginner and covers all topics (from a user's perspective with > > typical > > use cases) in a sensible order from the easy to the complex. Something > > like a > > guide that answers among others the questions: > > - "What do I need to know first. Wich topics to learn in which order." > > - "Where find I more backgournd details about ...", > > - "What is the current state of GeoTools: What is it capable of, what > > not?") > > > > I've read a lot of good "all in one" tutorials/manuals of this sort, such > > as > > - "Version Control with Subversion" or the > > - "PostgreSQL 8.0.0 manual" (postgresql-8.0-A4), or > > - IDL tutorial/user's guides (They use linked PDFs and are excellent > > imho.) > > The uDig beginner's tutorial is also good in this respect, although it > > only > > covers the really simple things. > > > > The main point is, that the GeoTools learning curve is imho quite steep > > for the > > typical GIS user (not computer scientist), and this is even more > > pronounced by > > the fact that the API is changing fast. Sometimes I have the impression > > that as > > soon as I understand something it is about to change to something more > > complex > > in the next version. (In ecology this is called the "Red Queen hypothesis" > > - > > one has to run to stay on the same spot). > > It should imho be the task of a good documentation to shield the average > > user > > from this impression and the ongoing RnD work and to give him/her the > > feeling > > of working on a stable API. > > > > I'd like to help with documentation, but as long as I havn't understood > > most > > APIs myself I doubt this makes much sense. > > > > 4. Spin-off ... and back in > > --------------------------- > > It became obvious that there is often the need (and will be always) for > > some > > stakeholders to create some functionality quickly (often under pressure of > > a > > deadline). They can often not wait for the complete release cycle > > including the > > steps discussed in point 1. uDig - it seems - has tought us some lessons. > > > > My idea is that there should - for each project working on top of Geotools > > - be > > three "workspaces" (any better word appreciated): > > - GeoTools workspace > > - GeoTools-aimed quick and dirty workspace > > - Application workspace > > > > The "GeoTools workspace" holds what is where in GeoTools or what can be > > quickly > > incorporated or can be incorporated in the usual GeoTools release cycle. > > > > The "Quick and dirty workspace" is for work that is aimed to be > > incorporated > > into GeoTools later, but (since under time pressure) cannot run through > > the > > offical GeoTools release cycle but is needed to run, f.e., earlier than > > the > > next release. It would be part of the application until it becomes > > incorporated > > into the GeoTools workspace (after approval). > > The point is that this workspace would follow certain GeoTools developer > > rules: > > - no dependencies on application specific libraries or modules (i.e. > > independence from the "Application workspace"). > > - follow GeoTools coding guidelines as far as possible This ensures that > > incorporation into GeoTools will later work with as few problems as > > possible. > > Both GeoTools and application developers should have access to this > > workspace. > > > > The "Application workspace" would hold any code that is not supposed to > > become > > part of GeoTools later. > > > > 5. Facades, two-level API > > ------------------------- > > I believe that GeoTools could become a much more user-friendly API if it > > had a > > strict two-level API and developer guidelines that facilitate it. > > > > - A high-level API with functions as the usual GIS USER(!) would expect > > them. > > - Typical GIS terminology for functions > > - Task-based, liberal API (just have the really necessary functions and > > methods in the interfaces, implementations have the freedom to perform > > the tasks as they like.) > > - No use of "Blackboards", "visitors" or any advanced Java techniques > > (Users should not need to read the GOF's book to understand it). > > - Hiding of different implemetations (remote vs. local, DB vs. file, > > different specification versions etc. ) > > - Hiding of "complex" things, even if this covers only > > 95% of the functionality > > - Hiding of performance tweaks > > - STABLE over several versions of GeoTools > > - Well-documented extension/entry points, f.e. to do scientific stuff > > with the data, add a new file format, ... (It is my impression that this > > works quite well in uDig already.) > > > > - A lower-level API with functions as the COMPUTER EXPERT would require > > them > > - access complete functionality, including "complex" extensions > > - possibility to change implementation at a quicker rate, incorporate > > tweaks > > - everything allowed... > > - interfaces more closely mirroring the OGC (or other) specifications. > > > > Not all parts of GeoTools need such two level API. I consider it very > > important > > for > > - Styling API. The GeoAPI interfaces are NOT what a GIS user would expect. > > - Features/attributes (Most GIS users see the classical shapefile > > attribute > > table before their eyes when they hear "attributes", and a high level API > > should imho try to reflect this.) > > - Data I/O (There is a high level API there as a good starting point.) > > - Geometry/Topology API? Not sure. > > > > I consider it not necessary for > > - MapFramework API (There isn't anything complex to hide yet.) > > - Referencing API (This is already intuitive in my opinion.) > > - Rendering (This is not something a GIS user would usually care about. > > It is expected to "simply work".) > > > > OK. These are just mine ideas. > > > > Matthias Basler > > [EMAIL PROTECTED] > > > > > > ---------------------------------------------------------------- > > This mail was sent through http://webmail.uni-jena.de > > > > > > ------------------------------------------------------- > > SF.Net email is sponsored by: > > Tame your development challenges with Apache's Geronimo App Server. > > Download it for free - -and be entered to win a 42" plasma tv or your very > > own Sony(tm)PSP. Click here to play: http://sourceforge.net/geronimo.php > > _______________________________________________ > > Geotools-devel mailing list > > [email protected] > > https://lists.sourceforge.net/lists/listinfo/geotools-devel > > > -- ------------------------------------------------------- This SF.Net email is sponsored by: Power Architecture Resource Center: Free content, downloads, discussions, and more. http://solutions.newsforge.com/ibmarch.tmpl _______________________________________________ Geotools-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/geotools-devel
