Here's a standard-ish Ant (or Maven or Centipede) layout.
/license.txt, /readme.txt, etc.
/build.xml is the Ant buildfile
/src/java is where most code goes
/src/test contains any unit tests
Something like /docs or /src/docs contains documentation (in what format? Is the website kept in CVS? Is the website the same as the documentation?)
Launch scripts in something like /bin or /src/bin
/lib/*.jar is where any dependancies go, if necessary
Ant targets:
compile (just makes classfiles)
build (compile + jar + copy over scripts)
dist (build + copy documentation and compress it all)
clean (delete the work directory)
-----
Using branches to track stable vs. unstable and release versions:
Keep everything in one CVS module for now. The trunk (the default branch, HEAD) is the development/unstable version. It may not be stable, but it should at least compile and run 99% of the time. If a large change involves temporarily making the code unusuable, that change should be done on a special branch and merged when it is at least semi-usable.
Before a release, branch off the HEAD into a release branch (named something like "release_1_0_branch") if unstable development needs to continue also. An alternative is the pre-release code freeze for development other than bug-fixing. Either way, tag before a release (something like "release_1_0"). If you don't merge the release branch back into the HEAD, it becomes easy to make bug-fix releases of old versions.
-----
That's all that jumps to mind.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Ok, this sounds sensible. If it's ok with you, I think the best would be if you'd do the job of laying out our CVS repository at this point. If you do, use the files in the current "unstable" module, since these are newer than the ones in the pre-release archive.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I tried refactoring a bit to see if I could fix some of the limitations imposed by the original design. Just as an example, there was a comment in Bibitem that mentioned a problem marking the required an optional fields for a book -- either author or editor must be present, but you don't need both. The table-based approach doesn't allow much flexiblity with rules like that. I tried to slowly refactor away the table, but eventually I got stuck and decided to start an alternative version from scratch to see where it goes.
I've barely made any progress, but you can review what I have now or wait until it grows a bit and see what you like and don't like. I'm using Test Driven Development, so I've also got unit tests for the stuff I've written so far.
My work is in a branch named alternate_version (http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/bibkeeper/unstable/?only_with_tag=alternate_version) .
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
'ant dist' works fine; I've had a look at ant, and I'm going to check out Junit - these are tools I haven't been aware that I needed. I'm learning a lot about software development right now, so you'll have to bear with my ignorance about these things for a while.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
You haven't needed them, and you still don't ;). JUnit you may ignore if you like. I'm somewhat influenced by a methodology called Extreme Programming which places a high value on automated testing. I like the comfort of knowing that my software is at least 90% functional.
Ant is just an extremely useful buildtool. It keeps getting awards from magazines like JavaWorld for being the most useful community-developed technology. It really is quite a handy tool.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I think JUnit has a learning curve; I didn't quite grasp it yesterday, but I still think it can be useful. Du you prefer the GUI or the command-line version for running tests? Ant is definitely useful, and I found it quite appealing, and easy to use; after five minutes I was able to set up the build file as I wanted (for compiling, moving some files, creating a tar.gz archive, etc.)
For the GUI of Bibkeeper, I think I'd like to use some of the classes from the Graphic Java Toolkit; they make it easier to put in toolbars, image buttons and other nice-looking components. The toolkit comes with a book from Sun, 'Graphic Java', and according to the licence agreement (http://sunsite.ccu.edu.tw/books/books/Geary/geary_agreement.html) there shouldn't be any problem using it. I don't suppose this conflicts in any way with the GNU licence?
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I run JUnit two ways. One is to use the built-in support of the Eclipse IDE (my prefered Java editor). It's graphical and lets you double click on stack traces to go the the code, works conveniently as you code, etc.
If you look on the alternate_version branch, I've also got Ant set up to run unit tests on "ant test" that output text (to the console and build/tests/). For Ant to run JUnit the best option is to copy junit.jar into ant/lib along next to optional.jar.
As a developer, I like Test Driven Development because the little green light tells me I've accomplished something. Unit tests are also a great way to catch bugs where you break something that used to work.
I'm downloading "Graphic Java Toolkit" and I'll check it out soon. It seems to be freely distributable so licensing shouldn't be a problem. I've had a few brief interactions with Swing, but I'm an AWT virgin. I usually prefer to watch GUI's from a safe distance away ;).
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Actually, I did some thinking yesterday, and I think I should use Swing components instead of the old AWT ones. The GJT expands on the old ones, but Swing components offer the same flexibility and much more.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Your alternate version looks very good. I'll take their interface into account when continuing my work on the GUI. I have a couple of questions, but I'll put them in the Developers forum instead.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Some ideas/proposals:
-----
Project layout:
Here's a standard-ish Ant (or Maven or Centipede) layout.
/license.txt, /readme.txt, etc.
/build.xml is the Ant buildfile
/src/java is where most code goes
/src/test contains any unit tests
Something like /docs or /src/docs contains documentation (in what format? Is the website kept in CVS? Is the website the same as the documentation?)
Launch scripts in something like /bin or /src/bin
/lib/*.jar is where any dependancies go, if necessary
Ant targets:
compile (just makes classfiles)
build (compile + jar + copy over scripts)
dist (build + copy documentation and compress it all)
clean (delete the work directory)
-----
Using branches to track stable vs. unstable and release versions:
Keep everything in one CVS module for now. The trunk (the default branch, HEAD) is the development/unstable version. It may not be stable, but it should at least compile and run 99% of the time. If a large change involves temporarily making the code unusuable, that change should be done on a special branch and merged when it is at least semi-usable.
Before a release, branch off the HEAD into a release branch (named something like "release_1_0_branch") if unstable development needs to continue also. An alternative is the pre-release code freeze for development other than bug-fixing. Either way, tag before a release (something like "release_1_0"). If you don't merge the release branch back into the HEAD, it becomes easy to make bug-fix releases of old versions.
-----
That's all that jumps to mind.
Ok, this sounds sensible. If it's ok with you, I think the best would be if you'd do the job of laying out our CVS repository at this point. If you do, use the files in the current "unstable" module, since these are newer than the ones in the pre-release archive.
Since things aren't quite set in stone yet, I've kept working in the unstable module. Check out the changes and see if you can execute 'ant dist'.
The classes can't stay in the default package forever. Did you have anything in mind? If not, net.sf.bibkeeper is probably as good as anything.
I should also mention this:
I tried refactoring a bit to see if I could fix some of the limitations imposed by the original design. Just as an example, there was a comment in Bibitem that mentioned a problem marking the required an optional fields for a book -- either author or editor must be present, but you don't need both. The table-based approach doesn't allow much flexiblity with rules like that. I tried to slowly refactor away the table, but eventually I got stuck and decided to start an alternative version from scratch to see where it goes.
I've barely made any progress, but you can review what I have now or wait until it grows a bit and see what you like and don't like. I'm using Test Driven Development, so I've also got unit tests for the stuff I've written so far.
My work is in a branch named alternate_version (http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/bibkeeper/unstable/?only_with_tag=alternate_version) .
'ant dist' works fine; I've had a look at ant, and I'm going to check out Junit - these are tools I haven't been aware that I needed. I'm learning a lot about software development right now, so you'll have to bear with my ignorance about these things for a while.
"are tools I haven't been aware that I needed"
You haven't needed them, and you still don't ;). JUnit you may ignore if you like. I'm somewhat influenced by a methodology called Extreme Programming which places a high value on automated testing. I like the comfort of knowing that my software is at least 90% functional.
Ant is just an extremely useful buildtool. It keeps getting awards from magazines like JavaWorld for being the most useful community-developed technology. It really is quite a handy tool.
:)
I think JUnit has a learning curve; I didn't quite grasp it yesterday, but I still think it can be useful. Du you prefer the GUI or the command-line version for running tests? Ant is definitely useful, and I found it quite appealing, and easy to use; after five minutes I was able to set up the build file as I wanted (for compiling, moving some files, creating a tar.gz archive, etc.)
For the GUI of Bibkeeper, I think I'd like to use some of the classes from the Graphic Java Toolkit; they make it easier to put in toolbars, image buttons and other nice-looking components. The toolkit comes with a book from Sun, 'Graphic Java', and according to the licence agreement (http://sunsite.ccu.edu.tw/books/books/Geary/geary_agreement.html) there shouldn't be any problem using it. I don't suppose this conflicts in any way with the GNU licence?
I run JUnit two ways. One is to use the built-in support of the Eclipse IDE (my prefered Java editor). It's graphical and lets you double click on stack traces to go the the code, works conveniently as you code, etc.
If you look on the alternate_version branch, I've also got Ant set up to run unit tests on "ant test" that output text (to the console and build/tests/). For Ant to run JUnit the best option is to copy junit.jar into ant/lib along next to optional.jar.
As a developer, I like Test Driven Development because the little green light tells me I've accomplished something. Unit tests are also a great way to catch bugs where you break something that used to work.
I'm downloading "Graphic Java Toolkit" and I'll check it out soon. It seems to be freely distributable so licensing shouldn't be a problem. I've had a few brief interactions with Swing, but I'm an AWT virgin. I usually prefer to watch GUI's from a safe distance away ;).
Actually, I did some thinking yesterday, and I think I should use Swing components instead of the old AWT ones. The GJT expands on the old ones, but Swing components offer the same flexibility and much more.
Your alternate version looks very good. I'll take their interface into account when continuing my work on the GUI. I have a couple of questions, but I'll put them in the Developers forum instead.