| View previous topic :: View next topic |
| Author |
Message |
aldacron
Joined: 05 May 2004
Posts: 1322
Location: Seoul, South Korea
|
 Posted: Sun Mar 06, 2005 3:29 am Post subject: Documentation, releases, and samples |
 |
|
I have added a /docs directory to the trunk along with the first page of documentation. I have also changed the top-level README. More documentation will follow as I have time to add it. I also have a /samples directory in my working copy, but I have yet to add it to the trunk. I need to think a bit more on distribution.
The first release archive of Derelict was labelled as 'Derelict 0.1' and contained a directory tree quite different from that of the trunk. My thinking was that the trunk would be the place people interested in only certain packages could check them out individually, whereas the release archives would be for people who wanted everything in one place. So each package was lumped together in a common derelict directory. This is going to change, methinks.
Now I'm planning to just start labelling each Derelict release as 'Derelict Release #' (so the next release will be 'Derelict Release 2'). After all, what constitutes a 1.0 release of a collection of bindings? The 0.1 release will, henceforth, be known as 'Derelict Release 1'. I suppose bugfix releases, when needed, will be appended with a letter (Release 2a, 2b, 2c, and so on). This scheme makes more sense than going 0.2, 0.3, yadda, yadda until an arbitary 1.0.
As to the directory tree layout of the release archives, I'm now leaning toward using a snapshot of the trunk at the time of release. Using separate directory tree layouts could conceivably cause some confusion, but more importantly a single layout is consistent. If you work with the trunk one day and a release archive the next, it's all the same. That also means I don't have to maintain separate make files for the trunk and releases.
I'm debating how to handle the samples. I surely don't want to include SDL, GLFW and whatnot in the trunk. So, the dilemma is - include the samples in the trunk, or make them available as a separate download? Either way, should 3rd party libraries be included in a 'dependencies' download, or should the sample documenation provide links to the required files? I hate including the samples in the trunk if they can't be run right out of the box. Thoughts? |
|
| Back to top |
|
 |
clayasaurus
Joined: 21 May 2004
Posts: 857
|
| Posted: Mon May 02, 2005 4:13 pm Post subject: |
|
|
I think the users of derelict just want the bindings and can get the library dll/lib themselves, they also want sample code included with the library to show how it is used, and want simple build instructions so they can build the tests quickly and see if derelict works for them.
Also...
When users want to use derelict, they are usually looking for a specific library. So, if it is not too much trouble, would it be better to have a DerelictSDL.zip, DerelictGLFW.zip, Derelict*.zip, one for each library, and release/update them seperately as needed?
That way you can forget about release numbers, and instead just include a changelog with each release. |
|
| Back to top |
|
|
aldacron
Joined: 05 May 2004
Posts: 1322
Location: Seoul, South Korea
|
| Posted: Mon May 02, 2005 8:04 pm Post subject: |
|
|
| clayasaurus wrote: | | So, if it is not too much trouble, would it be better to have a DerelictSDL.zip, DerelictGLFW.zip, Derelict*.zip, one for each library, and release/update them seperately as needed? |
I just posted a reply explaining why in the beginning I decided against this sort of thing. But...
| clayasaurus wrote: |
That way you can forget about release numbers, and instead just include a changelog with each release. |
The more I think about this the more it makes sense. Versioning Derelict was something I was uncomfortable with, hence the idea of release 2, release 3, etc... But this just makes perfect sense. Then there's no pressure on me to get the next release archive of Derelict out, thereby holding everyone up while they wait for me to finish it. I just release a package when it's ready to go.
Assuming I go this route I will need to restructure the documentation. I shouldn't need to redo the build scripts. And the only drawback I can see is that people will inevitably download one package they want and overlook DerelictUtil. Other than that, I really don't see anything wrong with it.
Okay, Clay, you've given me food for thought. |
|
| Back to top |
|
|
JJR
Joined: 22 Feb 2004
Posts: 1104
|
| Posted: Thu May 05, 2005 1:33 pm Post subject: |
|
|
| Sounds like a good plan. |
|
| Back to top |
|
|
aldacron
Joined: 05 May 2004
Posts: 1322
Location: Seoul, South Korea
|
| Posted: Thu May 05, 2005 7:55 pm Post subject: |
|
|
I'm still considering this. I'm just stuck on how to handle the files in the top-level directory. I just don't like the idea of including them in each zip, but it seems like the best choice. Then there's the case of archives for Linux. Do I just leave them all as zips? Or do I need to package up some gzipped tars with Unix line endings on the files? Once I get support in for GDC on Mac, will I need separate archives for Mac dev?
Thinking. |
|
| Back to top |
|
|
JJR
Joined: 22 Feb 2004
Posts: 1104
|
| Posted: Thu May 05, 2005 10:23 pm Post subject: |
|
|
| aldacron wrote: | I'm still considering this. I'm just stuck on how to handle the files in the top-level directory. I just don't like the idea of including them in each zip, but it seems like the best choice. Then there's the case of archives for Linux. Do I just leave them all as zips? Or do I need to package up some gzipped tars with Unix line endings on the files? Once I get support in for GDC on Mac, will I need separate archives for Mac dev?
|
No. It's fine to leave them in the zip format. It's common enough even on linux platforms. Most linux's should support it out of the box. They tend to support a whole assortment of archiving formats now. I imagine it's a similar case on the Mac.
Concerning the separate archives, perhaps just stick a duplicate of DerelictUtil in each one of them for optional use? It's a pretty useful, if optional, part of Derelict.
Concerning the inclusion of samples, I think they should be made available in Derelict in some form. You don't have to put them in trunk, though. Likely better to put them in another directory all together so people can at least see how to use the libraries and how they perform (ie. separate download). I think your assessment is pretty close to the mark: including them in trunk would give the impression that they should work right out of the box. While we do need to have examples in there, that may not be the best location for them.
I have a few DerelictGLFW samples still available on Linux, so when things get sorted out in ragards to directory structure, I'll add them in.
-JJR |
|
| Back to top |
|
|
aldacron
Joined: 05 May 2004
Posts: 1322
Location: Seoul, South Korea
|
| Posted: Thu May 05, 2005 11:59 pm Post subject: |
|
|
| JJR wrote: |
Concerning the separate archives, perhaps just stick a duplicate of DerelictUtil in each one of them for optional use? It's a pretty useful, if optional, part of Derelict. |
DerelictUtil is not optional. Each package has a dependency upon it. It seems redundant to include it in each archive, but not doing so means you need to download 2 archives to get one.
| JJR wrote: |
Concerning the inclusion of samples, I think they should be made available in Derelict in some form. You don't have to put them in trunk, though. Likely better to put them in another directory all together so people can at least see how to use the libraries and how they perform (ie. separate download). I think your assessment is pretty close to the mark: including them in trunk would give the impression that they should work right out of the box. While we do need to have examples in there, that may not be the best location for them. |
If I move to individual archives, I was thinking about doing something different with samples. In that case, I'm of the mind that each package should be self contained - src, docs, and samples for that package all in its directory tree. And I'm thinking more now that the samples don't need to do anything more than show how to load the library and start using it. One basic sample for each package ought to be enough. But then we could throw in one or two more complex samples for good measure.
Ideally, what I'd like to do is to create a 'package builder' which lets the user select which Derelict package(s) to download, then dynamically create a zip containing the the selected packages + any unselected dependencies. So selecting DerelictSDLImage would create a zip containing DerelictSDLImage, DerelictSDL, DerelictUtil, plus the top-level docs and build scripts. I may talk to Brad and see if it would be possible to implement something like this on the download page. This would be so much more convenient for the client, as they would get precisely the packages they need without multiple downloads, and convenient for me because I wouldn't need to worry about updating the downloads. With Derek's permission, we could even have an option to bundle the latest version of Build. |
|
| Back to top |
|
|
Derek Parnell
Joined: 22 Apr 2004
Posts: 408
Location: Melbourne, Australia
|
| Posted: Fri May 06, 2005 12:40 am Post subject: |
|
|
| aldacron wrote: | | With Derek's permission, we could even have an option to bundle the latest version of Build. |
I have no problems with that.
_________________
--
Derek
skype name: derek.j.parnell |
|
| Back to top |
|
|
JJR
Joined: 22 Feb 2004
Posts: 1104
|
| Posted: Fri May 06, 2005 12:48 am Post subject: |
|
|
| aldacron wrote: | DerelictUtil is not optional. Each package has a dependency upon it. It seems redundant to include it in each archive, but not doing so means you need to download 2 archives to get one.
|
 Obviously my head is in the clouds. I must have forgotten that.
| aldacron wrote: | | If I move to individual archives, I was thinking about doing something different with samples. In that case, I'm of the mind that each package should be self contained - src, docs, and samples for that package all in its directory tree. And I'm thinking more now that the samples don't need to do anything more than show how to load the library and start using it. One basic sample for each package ought to be enough. But then we could throw in one or two more complex samples for good measure. |
Well... it looks like you came to a decision independently after all... that sounds workable. I guess it helps when certain people give you insipid suggestions. 
| aldacron wrote: | | Ideally, what I'd like to do is to create a 'package builder' which lets the user select which Derelict package(s) to download, then dynamically create a zip containing the the selected packages + any unselected dependencies. So selecting DerelictSDLImage would create a zip containing DerelictSDLImage, DerelictSDL, DerelictUtil, plus the top-level docs and build scripts. I may talk to Brad and see if it would be possible to implement something like this on the download page. This would be so much more convenient for the client, as they would get precisely the packages they need without multiple downloads, and convenient for me because I wouldn't need to worry about updating the downloads. With Derek's permission, we could even have an option to bundle the latest version of Build. |
That certainly sounds complicated. Nice for the users, of course, to get such a nifty system. All I can say is you sure like treating your Derelict users to dessert! Be warned, though, they might get fat and your library popular.
I'm sure Derek wouldn't mind at all if you included the build tool with the project. It's open source after all. The more people that use it, the better publicity for him and his tools. I can't see it being an issue of permission here... blessing maybe? Perhaps. I notice Charles uses "build" in his Elephant IDE already and displays Derek Parnell and "build" prominantly in the about box. Now that's advertising! 
Great job on the library, BTW. It is fast becoming the standard library for D graphics programming. The better it gets and the simpler it becomes to use can only drive it further into the forfront as D become more popular (hopefully). Maybe we should throw a GUI into it someday? For what it's worth, I think you're on the right track to success with Derelict.
-JJR |
|
| Back to top |
|
|
|
|
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
|
Powered by phpBB © 2001, 2005 phpBB Group
|
FAQ
Search
Memberlist
Usergroups
Register
Profile
Log in to check your private messages
Log in
