iProv Contributions

Overview

Anyone can download the XML file and play with it. In order to have your changes fed back up the chain and ultimately wind up somewhere visible (such as the iProv application), however, you need to have an account with SourceForge, be an approved contributor to the project, and make all your changes through the SVN revision-control system.

You do NOT have to be a computer expert to contribute to iProv, but it helps to be computer-literate. Mostly you just need to be willing to follow the instructions.

Steps

1. Register for an account with SourceForge

   You can register here. Make sure you complete the registration by following the instructions e-mailed to you by SourceForge. Be sure to note your Username and remember your Password, as you will need these.

2. Send an introductory email

   Send a brief email with your SourceForge Username to contributor-requests@iprov.org to request contributor access to the SVN repository. (It would be nice if you included something about who you are, who you perform/have performed with, what geographical region you're from, etc.) One of the project administrators will grant your SourceForge account the necessary privileges; please be patient while they get around to it!

   You can continue with most of the other steps if you want after sending the email, however, you won't be able to Commit your changes until an administrator has added you to the project.

3. Download Tortoise SVN
   • Tortoise SVN is a free program that makes it easy to access SVN repositories from Windows.
   • Go to http://tortoisesvn.net/downloads and download and install the latest version for your computer. (If you're not sure which file is right for you, it's most likely the one with "win32" in the name and ends with ".msi".)
   • The installer will prompt you to restart your computer when it's completed, which you should do.
   • Mac users please see the Mac SVN instructions.

4. Check out the repository
   • In Windows, navigate to the folder you want to work on the iProv XML file in.
   • Right-click in any empty space in the window and choose "SVN Checkout..." from the sub-menu that appears.
   • Copy and paste the following into the field marked "URL of repository":

     https://iprov.svn.sourceforge.net/svnroot/iprov/

   • Leave everything else the same and click OK. (You will be prompted to create the "iprov" directory; go ahead and do so.)
   • Wait while the repository downloads, then click OK when it's done.

5. Edit the XML file
   You will notice two folders inside the new "iprov" directory: "iphone-draft" and "iphone-live".
   iphone-draft is the folder you will work out of, for draft revisions of the XML file. (iphone-live is the version currently published to the iPhone application; you may examine it if you want, but it's not meant for public modification.)
   Only make changes to the file inside iphone-draft, never iphone-live. Any changes made to iphone-live by unauthorized users will be discarded, and your work will be lost.
   Open the file items.xml in the folder iphone-draft.
• You can open the file in any text editor, including Windows' Notepad. Two free, more sophisticated text editors are ConTEXT and PSPad.
• You can also open the file in a program designed to work especially with XML, such as Microsoft's XML Notepad.
• Information on editing the XML file is here.
6. Commit your revisions
   Once you've saved your changes, you'll notice the little green checkmark on the file has changed to a red exclamation point.
   • Right-click on the file and choose "SVN Commit...".
   • In the box that appears, write a brief summary of your changes that anyone else who gets your update will be able to see. Press OK.
   • After a brief moment you will be prompted for your username and password. These are the Username and Password you created when registering for SourceForge. (You will be given the option to save your authentication data so you don't need to reenter it each time.)

   Congratulations! You've just posted your contribution to the rest of the world.

7. Stay updated
   If you ever go to commit your changes, and get the message "Commit failed ... resource out of date; try updating", it means that someone else committed a change that you don't yet have.
   • Right-click on the file, and choose "SVN Update". In most cases, the other changes will be merged seamlessly with yours.
   • Attempt to commit your changes as in the previous step. This time they should go through.
   • In some cases, conflicts may exist between the most recent version and your version. When this happens, you'll be given the opportunity to compare the different versions and fix any conflicts.

   Best practices are to always Update the file before you go to make any changes, and to Commit your changes regularly and in small increments rather than all over the place in one go.

8. Stay committed to quality
   Please read and respect the guidelines for editing the XML file.

   This is an open project but it is managed and edited by people who care deeply for the quality of it, and contributions that are inconsistent with the rest of the file, break with its conventions or are otherwise deemed unhelpful or incomplete are likely to be cut.

   People who repeatedly ignore or abuse the guidelines will lose the ability to make changes.

   Do not make changes to the files in iphone-live. You will lose your contributions and it's a fast track to losing your account privileges as well.

   Respect the work of your fellow contributors and the decisions of the editors (who have to consider the effectiveness of the document as a whole).

   Respect.

   

   ---