Difference between revisions of "Dev Getting Started"

Revision as of 05:51, 21 August 2011

Welcome to Dreamwidth code development! This page is a guide to how to get started with hacking on the Dreamwidth code.

The languages and skills Dreamwidth development uses are:

• Perl (the majority of the project)
• BML (custom templating language inherited from LiveJournal)
• TT (Template Toolkit - better templating language, used for new pages)
• HTML
• Javascript / JQuery
• MySQL and DBI (the Perl interface to MySQL and other SQL databases)

To hack on the Dreamwidth code, you'll need a development environment: a place where you can install the Dreamwidth code yourself, to make changes and generate patches.

If you have the means and desire to install your own development environment, there are resources in the Dreamwidth Installation category. The original LJ Server documentation is here. (We know that the install documentation isn't all that great at the moment, and we'd love it if you keep notes on this wiki as you go.) There have also been some useful posts to the dw_dev community, under the install issues tag.

If all of that seems like too much of a headache, we offer hosted sandbox development environments where we'll install the code for you. We call them Dreamhacks, and they're available free of charge for anyone who's interested in contributing to the project. Information on how to apply can be found at the main Dreamhack page.

The short version

For those who are experienced enough to not need a walkthrough:

To browse the Dreamwidth code, you can look at the Mercurial repository; the main parts of the code you will be interested in are in dw-free. To see the changes being made to the Dreamwidth code, look at changelog, which automatically posts commits.

Information on how to set up a development environment from scratch is at Dreamwidth Scratch Installation.

You can find information on how to keep your code updated on Dev Maintenance, information on programming style on Dev Programming Guidelines, information on finding things in Dev Finding Things, and information on submitting patches on Dev Patches. There is a comprehensive bug list as well as other useful info on Bugzilla. See Development for a more complete reading list, or look through the pages in Category:Development.

Before any of your patches are committed, we'll need a contributor licensing agreement on file from you.

Developers should check out the documentation on Design as well.

The long version

If you're totally new to programming and/or contributing to Open Source projects, don't worry! We'll walk you through the process.

Your best source of real-time information, including help for what to do when you totally break something, is the #dreamwidth-dev IRC channel, where there are people willing to mentor who can figure out where your abilities are at and how to best apply them. We also have a Dreamwidth community: dw_dev_training. It's a good idea to watch both that and the dw_dev community.

Here's a step-by-step checklist for getting started hacking on the Dreamwidth code.

1. Get a development environment. We run the Dreamhack service so you won't have to install and configure the code yourself, so all you need to do is apply for a Dreamhack account.

2. Read over the Beginning dev checklist and follow along with the steps for getting your Dreamhack account set up. Most of these steps are tasks you'll only have to do once to make sure your development environment is set up to hack on.

3. If you run into problems and have to ask for help, be sure to make a note on the Dev Wanted How-To or Installation Wanted How-To pages after you get the problem fixed, so someone can make sure to document it for someone else having the same problem. (Or, write a Wiki article on how you fixed it! Even if you don't entirely understand the fix, you can write down the steps you took to fix the problem as a starting point.)

4. Familiarize yourself with Perl, the language that the majority of DW development is done in. The best reference that we've found to point people at is Picking Up Perl. You absolutely don't need to be a Perl guru to submit a patch, but you should be familiar with the basic syntax.

5. Browse through some of the Dreamwidth source code to get a good sense of where things are and what the setup looks like. The basic directory structure, as well as some guidelines about what goes where, can be found in Main development folder.

6. Read the Programming Guidelines. (You may not understand all of the items there, but you can familiarize yourself with them, and start noticing when existing code doesn't follow the rules as you read.)

7. Send in a signed Contributor Licensing Agreement, or CLA. We need to have that on file before we accept any of your contributions.

8. Pick a bug that you want to work on! Some useful Bugzilla searches are pre-recorded for you: go to the Preferences link and pick the Saved Searches tab. You probably want to at least look at the all-unassigned query, and probably want to also look at the unassigned-effortminor query (as the ones that are most likely suitable for beginning developers). From time to time, people also post lists of "babydev bait" to dw_dev_training.

9. Set the bug to "Assigned" and put your Bugzilla email address in the "Assigned To" field. This tells people that you're working on it.

10. Make your fixes. Be sure to test! It's a good idea to test multiple use cases, including logged in/not logged in, community vs personal journal (if applicable), personal journal with different settings, etc.

11. Generate a patch and upload it to Bugzilla. Be sure to set the review? and commit? flags, so code reviewers and committers know about your patch and can review it.

12. If your patch passes review, it'll be committed. If there are things that could be improved, the reviewer will set the flags to commit- and review- and give you notes on what can be improved. Don't worry if your patch doesn't pass review on the first time -- it's really common for patches to go through several versions before they're committed.

What'd we miss?

If you run into anything in the process that isn't well-documented, or you have questions, you can ask in the dw_dev_training community or in the #dreamwidth-dev irc channel. You should also make a note on the Dev Wanted How-To or Installation Wanted How-To wiki pages so we can document it better for the next person to come along!