Netjuke Manifest
Blake Watters <sbw@ibiblio.org>
Initial revision : 1/21/2003

Introduction:

	Hello and welcome. If you are reading this, I can only assume that you are interested in, actively participating in, or 
curious about the development of the Netjuke streaming music server. This document will (hopefully) provide some insight into the
development process, the changes that have been happening recently, and where I hope to take Netjuke in the future.

Policies:

1. What you give to one, you give to all.
	Netjuke is inherently cross-platform. This is a wonderful aspect of the project, but it also introduces some constraints in
	the development process. Keep the cross-platform nature in mind -- no feature will be implemented for release purposes that is
	not tested on the platforms we support (currently, Linux, Mac OS X, Windows and most other similar unices).

2. Internationalize Everything!
        If you are developing for Netjuke or just want to submit a patch that scratches your own personal itch, wonderful! But please
        be aware that Netjuke is multi-lingual and ALL strings present in the interface must be internationalized. The language packs 
        can be found in netjuke-root/etc/locale/xx (where xx is a two character string for the language). Use them! It's not hard.
        Failure to do so greatly diminishes the value of your contribution as one of us will have to come behind you, figure out your 
        work, and then fix it to conform to the language conventions. If you can't handle the language packs, then just file a feature 
        request. In many cases it will take less time to develop that slick feature you dreamed up the right way than it will for us to
        fix it after the fact.
        
3. Coding Conventions
        Netjuke is a fairly large piece of code and is meant to be developed by (hopefully!) more than one person at a time. As such, 
        we have to conform to a common set of coding conventions to keep the source coherent and the learning curve low. To this end, 
        I have attempted to reduce the existing style to a set of rules and fill in the gaps with my own preferences:
                1. All php tags should begin with <?php as it is the most portable.
                2. All includes/requires should be done using the 'require_once' directive.
                3. Indention will be done with tab-stops of two spaces.
                4. Function names will be defined using capital letters for each meaningful part of the name without the use of
                        underscores. i.e. ThisIsAFunction (), MeToo (), StartTheMusic ()
                5. Variable names should be kept to a balance between mnemonic significance and length. Common sense is a plus 
                        in this area, as it can be highly subjective. Underscores are permitted. Examples : $dbconn, $path_name, login_time
                6. Constants should be defined in all capital letters, with underscores separating the meaningful parts of the name.
                        Examples : DATABASE_LOGIN, HEADER_HTML, etc.
                7. Braces should open on the same line as the block of code and the block should be closed by placing the closing
                        brace in line with the first character of the opening statements. Additionaly, a single blank line should 
                        be left following the opening line and preceding the closing. Example : 
                        
                        if (IsUserValid ($user_name)) {
                                
                                // do some stuff
                                
                        }
                8. Comment things that are unclear or to signify a change in the logical flow of the code. In short, comment anything 
                        you think that YOU would need to ask about if left uncommented, but resist the urge to become overly verbose 
                        and clutter the codebase with useless comments. Further more, use C style (/* */) for all multi-line comments 
                        and C++ style (//) for single line comments. Do NOT use Perl/Shell style comments (#). Examples:
                        
                        // Encode the password to keep away wandering eyes
                        
                        /*
                           
                           Here we begin the process of creating a secure, yet portable session ID.
                           We have to keep in mind that not all user-agents are created equally and
                           try to strike a balance between security and accessability.
                           
                        */
                9. Check your errors and report them properly! Suppress all internal PHP errors when commiting your code (@function-call), 
                        as they are both ugly and extremely jarring to a user. Users should NEVER see any errors except those reported to 
                        them intentionally.
                        
                        Incorrect example: 
                                mkdir ($some_directory);
                        
                        Correct example:
                                if (! @file_exists ($some_directory)) {
                                
                                        $success = @mkdir ($some_directory);
                                        if (! $success) {
                                                
                                                alert (FS_PERM_ERROR);
                                                
                                        }
                                        
                                }
                10. Attempt to keep your code as modular as possible. Before hacking a new feature into an existing file/function, ask 
                        yourself if this is something that could be isolated and thus made more reusable. If you're unsure of the answer, 
                        bring the question to the mailing list and we'll sort it out together.
                11. If you make changes to the preferences system, integrate these changes into the installer.
	
TODO (or "What can I do to help?"):
      There are many ways that you can help the development of the Netjuke -- and they are not necesarilly limited to contributing code
      (though this is what we are primarilly concerned with here ;). Additionally, you might want to consider:
        a. Activism - Share the wonders of Netjuke with your friends and family! Promote it among software websites you frequent!
           Just tell people how you feel!
        b. Documentation - Are you a saavy user of some obscure platform? Why not write up a document explaining what you did to get things
           working? Give back a little of your insight to the community and we'll be able to support more users and reach a wider audience.
        c. Support - If you've got a few minutes, why not take a look through the forums or jump on a mailing list and see if you can't help
           some people out? Answers can sometimes go much further than code.
      
      Additionally, there are still a lot of things you can do as far as contributing code. As mature as the Netjuke is, we still have quite
        a bit of room for improvement and innovation. So take a look below and see if you can find anything that seems like something you 
        would like to take a stab at.
        
- Expand the audience
1. Translations - The more the merrier. Netjuke is designed for internationalization. Let's see how international we can be
	a. Translate existing language packs to new languages
	b. Pool all common strings and place them into a common language file (possibly to be auto-included on every page?) This will take some
		of the load off of the translators and prevent duplication of effort.
2. Databases - Adodb supports a whole slew of databases. Let's see to it that Netjuke does the same.
	a. Oracle - Similar to Postgres, should be a relatively trivial port.
	b. MSSQL - This could be a bit trickier. But I'm sure the Windows users would love to see it.
	c. Access - Same deal as b.
	d. Firebird - Open Source DB derived from ibase. Interesting :)
	e. SAP DB - Another OS DB.
	d. Others - I'm ready to support whatever there is demand for ;)
3. Platforms - We should be able to support netjuke on nearly any platform that allows for a PHP runtime environment. 
   These platforms need testing:
	a. Windows pre-2k/NT
	b. FreeBSD
	c. OpenBSD
	d. NetBSD
4. Help System -  This should be integrated into the main toolbar and outline how to get around the system, document where to go for help, etc.

- Enrich the codebase
1. Administrative Features - 
        a. Detect tag changes in importer/maintain utility
        b. Improved logging/statistics
        c. Genre control
2. Streaming radio additions - Control a streaming radio system entirely through netjuke UI
        a. 'Publish' playlists
        b. Dynamically create streams from genre, artists, etc.
        c. Rework 'Radio' section into nice front-end displaying the status of radio streams.
3. RSS syndication of 'latest' lists
4. Rework error reporting
5. Addition of 'Year' field to search functions
6. Cleanups - this is all super non-sexy stuff that I'll probably have to do :)
        a. Make sure all code conforms to the above guidelines
        b. Modularize as much as possible
        c. Make sure we're displaying cleanly on a variety of browsers

- Interesting Novelties
1. Winamp Minibrowser - It would be interesting to see a Netjuke window displaying metadata for winamp minibrowser clients.
2. Mozilla sidebar - A quick sidebar for mozilla to search Netjuke could be interesting for the Mozilla based clients.
3. MusicBrainz metadata integration - MusicBrainz has an interesting looking RDF based service. Being able to exchange metadata with
        MusicBrainz could be very useful.

- The Future
  Within several months of this writing I hope to release Netjuke v1.0 and immediately begin work on the next version. The fundamental
focus for Netjuke v2.0 will be to convert the entirety of the Netjuke backend into a modular XML-enabled framework and reimplement the
HTML front-end as a client to the XML backend. This is going to entail a new XML-RPC or SOAP powered backend, the details of which will 
be determined over the next several months on the mailing lists. From this point, development can shift to developing new client interfaces
to the netjuke backend. I'd like to see an X-Windows iTunes clone (maybe Rhythm Box?) with a slick netjuke backend plugin. But that's just 
me ;)
