Development
The source code for Vienna is available from SourceForge. This section is intended to help you get started with downloading and building Vienna on your own machine.
See the Vienna Subversion Page to quickly browse the Vienna sources. The rest of this page explains how to download the source to your machine.
What You Need
To build Vienna, you will need:
- Mac OSX 10.4 (Tiger) and Xcode 2.5.
- Subversion client 1.30 or later and a reasonable amount of experience using Subversion. See the SourceForge Subversion page for a tutorial.
To make modifications to the Vienna source code, you will need a working knowledge of Objective-C and the Cocoa framework.
See the Apple Developer's Web Site for more information on Xcode, Objective-C and Cocoa.
Localisations
If you would like to contribute to Vienna by creating a localised version, please see the Localisation section below.
Getting Started
The Vienna source code should be checked out to a folder whose path does not contain spaces. This is a limitation of the project file that will likely be fixed in the future but, for now, make sure the full path to the Vienna source folder does not have any spaces in it.
The 2.3.0 trunk contains the current release version and all changes should be contributed to this trunk.
Check out the sources via Subversion. Open a terminal window and enter:
svn co https://vienna-rss.svn.sourceforge.net/svnroot/vienna-rss/trunk/2.3.0
After the check out has completed, start Xcode and open the Vienna.xcodeproj file. Do a build and run, and you're ready to go.
You should regularly update your snapshot of the source from the master tree. To do this, run the following command from the folder containing the source code:
svn update
Contributing Changes
I welcome improvements and bug fixes to the Vienna source code. While you are free as per the terms of the Apache 2.0 license to reuse parts of the Vienna code in your own project, please consider contributing any improvements in Vienna itself back to me so I can review and add to the main source tree.
If you are looking for ideas to work on, please see the Vienna Bug Tracker for bugs that need fixing or the file TODO in Vienna's source code folder for features that have been requested. Please let us know what you are working on by posting a note in the Vienna Development Forum. Feel free as well to post any questions or comments you may have about Vienna development. We're happy to help, and we encourage developers to join the Vienna project.
Right now the documentation for the source is in the source itself. Read the comments and use the debugger to work out which functions do what. If the code becomes large enough then I might write a high level architecture overview but right now the source code is documentation enough.
If you are contributing changes, please ensure you follow the coding style used by the rest of the code. That means - function header style, nesting, spacing between keywords, etc. Consistency is important here.
To contribute changes, create a patch of the diffs against the latest Subversion snapshot of the source:
svn diff > mypatch.diff
and send it to vienna-rss-patches@lists.sourceforge.net.
Mailing Lists
Vienna development is discussed over in the Vienna Development Forum on CocoaForge.
You can also subscribe to a mailing list to be notified whenever new changes are committed to the source repository. See the Mailing Lists for Vienna page for instructions to subscribe to the list.
Coding Guidelines
I don't accept patches unconditionally. While the license for Vienna permits you to make your own changes and redistribute them as you see fit, I have my own quality bar for changes that are submitted to the official build so please take a moment to read the below before you start making changes.
- Source code style is crucial. Look at the existing code and note the layout of the code, the use of tabs vs. spaces, braces, indents and spaces before and after parenthesis and pointers. I'll make minor cleanups if necessary but if your contribution is large and doesn't adhere to the style of the rest of the code, I'll bounce it back for cleanup.
- Every function has a comment block at the beginning. If you add new functions, add comments. They are there to help with future source code indexing and also to make sure that the intent and usage of the function is clear to anybody who maintains it in future.
- If you want to pick something from the wishlist to implement then let me know first so I can mark it as "in progress" and avoid duplicate effort.
- UI changes have a high bar and I recommend you discuss your idea with me first before going ahead and implementing. The UI for Vienna is pretty much its brand identity and I'm somewhat protective of that. I do acknowledge that there needs to be improvements in some places but care needs to be taken to avoid overloading it.
- Non-UI changes don't have such a high bar so if you have a patch or a nifty idea, feel free to code it up and send it on.
- I review all patches before I accept them. For small bugs I'll probably make any fixes myself. Larger problems get bounced back for correction.
Localisation
I welcome volunteers who are willing to localise the Vienna resources into other languages. The below table shows the current languages into which Vienna is already localised:
- English
- Swedish
- French
- Italian
- German
- Dutch
- Traditional Chinese
- Spanish
- Japanese
- Korean
- Brazilian Portuguese
- Simplified Chinese
- Danish
- Czech
- Euskara (Basque)
- Ukrainian
- Russian
- Portuguese
Additional languages planned for which volunteers are needed:
- Arabic
- Polish
- Hebrew
If you wish to volunteer to localise Vienna for any of the above languages, post a message at the support forum.
Tools
To create localised versions of Vienna, you will need the same tools that are required to build Vienna. If you would prefer to work outside of Subversion, then an alternative approach is to copy the English.lproj file from the most recent build of Vienna and work on that.
Apple provides tools on its web site that may help you with your efforts. Note that I don't mandate the use of any specific tools. It is up to you to use whatever you find works best for you.
You need Subversion to enlist in the source code and obtain the latest changes in the English.lproj folder for localisation.
Instructions
[Additional instructions to go here].