-
Notifications
You must be signed in to change notification settings - Fork 0
Transitions
Like any large system, new developers to the Mobile Trail Mapping project can get lost in the magnitude of the codebase or the splits between the various platforms. This document is aimed at helping newcomers to MTM pick up the code structure, style, and functionality of the various code repositories in the project.
This document is not meant to be a replacement for the rest of the information available throughout this wiki. For example, the system architectures are not documented here, since they have their own page elsewhere. In addition, this document is meant to be somewhat less technical than the rest of the wiki; new developers and power users should start here before delving into technical details.
The MTM project is meant to provide a mapping interface for trails in Linn County, Iowa. To accomplish this, the project has four major components:
- An iPhone application
- An Android application
- A server to provide mapping data
- A self-contained web site for administration
In coding the MTM project, the developers use a version control system called Git. Git is a source control system: it lets developers track changes to the MTM code and make the project available for editing by others. This website, GitHub, is simply a window into the Git system used to track MTM code. Before getting started, new developers need to register for GitHub accounts and be added to the project by an existing development team member. They also need to install the Git tools for their particular platform.
Though this document cannot cover the full complexities of Git, it can walk through the basics of getting and editing the code for a particular project.
First, a developer decides to make a change to an MTM project. It is important to isolate which project needs a change: generally, phone application changes should be made in the iPhone or Android repositories, while changes to server functionality or administration happen in the server or frontend repositories. Changes to communications - how the server sends or receives data - will likely affect all four repositories simultaneously.
Say, for example, the developer wants to alter the iPhone application. He or she would first need to clone the repository onto a local machine; the repository URL is available on that repository's GitHub page. For the iPhone app, it is:
https://github.com/Mobile-Trail-Mapping/iPhone.git
Once cloned, the developer can do one of three things:
- Make changes to the local copy of the application, then commit them to the local repository
- Pull remote changes (made by other developers) to update the local copy
- Push local commits to GitHub, changing publicly available code
Each of these steps are explained in more detail in the official Git tutorial.
After changes are made and tested, the next logical step is to make the new, improved applications available to end users. How can a developer do that? The process varies for each subproject.
Both the iPhone and Android applications are published through their respective application stores, so to release either application, it must be built, packaged, and submitted to the relevant company. For more detailed instructions, refer to:
- The iOS Dev Center for the iPhone app
- The Publishing on Android Market page for the Android app
Deploying the server and administrative Web site are simpler: just copy the working source code into the appropriate directory on the web host. The MTM project uses HostGator for its hosting needs; at present, the MTM server code has its own folder within the linncountytrails.org server home. A deployment consists simply of copying updated code from the GitHub repository into that folder, replacing old code. (Remember that GitHub provides complete package downloads for all repositories!)
Barring major new developments in the MTM requirements or environment, the majority of changes to MTM code at this point are expected to be maintenance changes and bugfixes. As such, it's important for maintainers to be able to pinpoint problems and make code changes to the right project efficiently. A short list of symptoms and their probable locations follows:
- If the problem is in a mobile application's user interface, make the change to the relevant mobile app repository.
- If the problem is in data displayed on a mobile application, double-check the app's code to see that it is receiving the right data from the server. If it is, change the app; if the server is providing bad data, alter the server.
- If the problem is in device/server communications, check the Server API page, then check both the mobile app and server code to make sure each conforms to that API.
- If the problem is in online administration or online UI and appearance, make changes to the Web frontend repository.
- If the problem is in data displayed online, make changes to the server repository.
Remember that bugs will often appear across multiple platforms, as the mobile apps and Web frontend are both tightly tied into the server!
With that basic introduction, developers should be ready to delve into the MTM project! However, the original team strongly recommends a little additional reading before committing large changes:
- The system architecture document gives a much more technical breakdown of each MTM project. Developers must have a working knowledge of an app's architecture before making changes.
- Read the code! Individual repository codebases can be browsed through GitHub, and there is no harm in reading code online or even cloning a repository and playing with it locally before committing changes. Helpful comments and other documentation pointers are also scattered through the code for more detailed information.
On behalf of the team, welcome to MTM!