Contributing to AMOS

How do you contribute to AMOS?

Necessary Prerequisites

1. Bitbucket Account - The AMOS code source is available in a repository hosted by Bitbucket. It is important to have a Bitbucket account in order to download the code.

2. Authenticated user with AMOS - In order to have access to the AMOS source code, you must be an authenticated contributer to the AMOS project. These credentials can be obtained by contacting Dr. Robert Pless for more information!

3. Working development server - It is required that you have a working development AMOS server. If you do not, but still want to contribute to AMOS, follow the instructions to install a development AMOS server.

4. You know what you are doing! - AMOS is used throughout the world, so please have a background in computer science before contributing. We don't want AMOS to go down!

Changing AMOS

1. Pulling from the repository

Contributions are frequently made to the AMOS codebase. Because of this, files you are working on may change with out you knowing, and this will cause conflicts (or merge errors) when you try to push your code to the AMOS repository. To avoid the frustration of these conflicts, it is important to frequently pull code from the AMOS repository to your local development server. To pull from the AMOS repository and update your local copies of the files, follow these commands:
chris:archiveofmanyoutdoorscenes $ hg pull
chris:archiveofmanyoutdoorscenes $ hg update
2. Committing and pushing the code

Once you have made (and tested) your changes, you can commit the changes, and then push them to the AMOS repository. To do this, follow these instructions:
chris:archiveofmanyoutdoorscenes $ hg commit -u [[username]]
You will then be asked to enter a commit message in your default text editor (For example, I am asked to enter a commit message in vim). Enter in a concise message of the changes you made, and then exit the text editor. You may be asked for a password, and then it should give you a success message. At this point, you have committed your changes, and now you need to push the code to the repository. [[ADD MORE EXAMPLES, CLEAN WORDING]] To push your code to the AMOS repository, follow this command:
chris:archiveofmanyoutdoorscenes $ hg push
Enter in your username and password if asked, and then you should receive a success message (if not, see "Merge Conflicts")

3. Restarting apache

In order for you code changes to become live on the server, you must pull the code onto the server and restart Apache.

If you are associated with the Media and Machines Lab, then follow these commands:
chris $ ssh's password: 
Last login: Tue Dec  4 00:20:09 2012 from
username@amos2012 ~ $ cd /export/amos/archiveofmanyoutdoorscenes/
username@amos2012 archiveofmanyoutdoorscenes $ hg pull
username@amos2012 archiveofmanyoutdoorscenes $ hg update
username@amos2012 archiveofmanyoutdoorscenes $ python
This will fully update the server with the AMOS codebase, and then force apache to start serving the new information.

If you are NOT associated with the Media and Machines Lab, then please contact Dr. Robert Pless for further information.

4. Common errors

Here are a few common errors that can be expected during the process of contributing to AMOS.

1. Merge Conflicts

Merge conflicts are most often a result of two different people modifying the same code file simultaneously. It is very hard for Mercurial to decide which parts of the code to merge together, and so to be safe, it asks the user what to do. Most merge conflicts can be resolved by editing the file in question to incorporate both changes correctly, or simply replace the code with the most recent version. You can then commit this code to the repository.

2. Failing to commit new files

If a new file is added to the code project, Mercurial will not automatically add it to the repository. To fix this, run this command:
chris:archiveofmanyoutdoorscenes $ hg add
Then commit and push the code to the AMOS repository. Any newly added files will be added to the repository!

Handling Errors

What happens if something goes wrong?

1. Don't panic - Panicking will only make the problem worse.

2. Understand what went wrong - Locate the section of code that caused the problem, and try to figure out why the problem exists.

3. Fix the problem and test the fix - When you have figured out why there is a problem, make the appropriate fix, and then test that the fix worked. If, after thorough testing, the fix seems to work, then feel free to commit the code and update the server.

4. If you cannot fix the error- Contact a member of the Media and Machines Lab immediately, and they will be more than happy to help you!

Created by Chris Hawley