Dev_Developer Guidelines

Percy Liang edited this page Nov 15, 2015 · 9 revisions

Basic Requirements

Before working on CodaLab, you should be able to successfully build and run the project. Remember to follow basic Git hygiene. CodaLab is built using Python and Django, so you should be familiar with these technologies.

Branches

In the CodaLab Github Repo there may be many branches. We want to be very careful about two specific branches to ensure the quality of the codebase stays high.

  1. master - This is the stable version that is in production at any given time. It should be well tested and deployable.

  2. develop - This is the development branch. This is the branch that has all of the work that is thought to have been completed but has not yet undergone final testing before deployment to production. The develop branch is where automated builds and QA happens.

Get the Source Code

Follow these instructions to create a local clone of the CodaLab source code.

  1. Fork the CodaLab repo from GitHub.

  2. Clone the fork to your local computer.

    git clone https://github.com/<username>/codalab.git
    

Create a 'blessed' Branch

Follow these optional steps to create a 'blessed' master branch, which is an "untouched" master that can be updated to get the latest changes with git pull.

  1. Open a command prompt and navigate to the CodaLab folder.
  2. Assign the original repo to a remote called "blessed".

    git remote add blessed https://github.com/codalab/codalab.git
    
  3. Get the latest changes from blessed:

    git checkout master
    git pull blessed master
    

Use Topic Branches

Topic branches are typically lightweight branches that you create locally and that have a name that is meaningful for you. They are where you might do work for a bug fix or feature (they're also called feature branches). Follow these steps to create a topic branch:

  1. In your GitHub repository, create a topic branch.

    git checkout -b branch_name

    Make all of your changes in the topic branch, and consider the master branch to be a reference of the latest version.

  2. Commit your changes: git commit -a -m "A meaningful description of my commit."

  3. Push your local changes to your fork: git push origin <branch_name> Now you're ready to make a pull request.

Pull Requests

When the code in your GitHub fork is ready to make its way into the master branch of the CodaLab GitHub account, you should submit a pull request. Be detailed in your description of the changes.

When you submit a pull request, GitHub will let you know if the request cannot be merged automatically. This GitHub page explains how to merge a pull request.

Other assumptions:

  • Committers will review pull requests and fold them into the master branch of the CodaLab account.
  • Developers should ask for code reviews of their code when they feel like it's getting ready to pull into master. This is easily done by adding github id's to the message on the pull request (mentioning them sends a notification).
  • If a change is going to affect the user experience, it should include code reviews/discussions (again through pull requests mentions) because this is a broad platform, intended for use by many diverse communities.
  • Merges to master and deployment to production will be done by the project QA/Release Engineer.
  • Secure data is being stored in a shared dropbox location.

Best practices

  • DO read and follow the process for managing tasks and bugs.
  • DO associate your commit with the issue that you are fixing. The mechanism for doing so is explained in this GitHub Blog entry and in this StackOverflow question.
  • DO ensure that the development environment runs on Windows and Linux. We want contributions from many developers irrespective of their favorite development platform.
  • DO make sure to add unit tests to the tests.py file as you add new features.
  • DO make sure to add unit tests to the tests.py file as you fix bugs that could have been fixed by unit testing.
  • DO use PyLint (as documented at https://github.com/codalab/codalab/wiki/Dev_Code-checkers) to validate your code matches this project's expectation of coding standards.

Additional Resources

Finally, here is some recommended reading for participating in an open source project: