Difference between revisions of "Dev Getting Started"

Revision as of 11:59, 1 August 2014

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

What you need

The languages and skills Dreamwidth development uses are:

• Perl (the majority of the project)
• BML (custom templating language inherited from LiveJournal which we are currently phasing out)
• TT (Template Toolkit - better templating language, used for new pages)
• S2 (custom templating language used in journal styles)
• HTML / CSS
• Javascript / JQuery
• MySQL and DBI (the Perl interface to MySQL and other SQL databases)

You don't need to know them all! Some familiarity with at least one will be helpful, but we welcome people at all levels, and are happy to answer questions and give advice as long as you're willing to learn.

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 submit them. 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. We also have instructions below if you want to set up your own, but be warned, it is a bit of a process.

The short version

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

Code and bug tracker

• Git repository on GitHub - public repository where you can browse the Dreamwidth code. The main parts of the code you will be interested in are in dw-free
• Issue tracker (GitHub Issues) - see also Github Issues
• changelog - changelog community on Dreamwidth which automatically posts commits

Development

• Development environment - you have two options
  • Apply for a Dreamhack - get a development environment with everything set up for you (preferred)
  • Dreamwidth Scratch Installation - set up a development environment from scratch
• Dev Finding Things - getting around the code base and figuring out where to start when looking for a specific feature
• Dev Programming Guidelines - programming style
• Design - things to keep in mind when designing features. Developers, please take note of this page!
• Dev Maintenance - how to keep your code updated
• Version Control - basic commands for keeping track of your changes using version control. Also includes instructions for submitting those changes via a pull request

Don't forget your contributor licensing agreement - we'll need one of these from you before we can accept any contributions.

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. Bookmark the dev pep-talk that occurred in IRC in early 2012. Also, have a look through the Epic List of Things Real Dreamwidth Programmers Do.
2. 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.
3. 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.
4. If you run into problems and have to ask for help, it would be great if you could describe the process in dw_dev_training, and ask someone with wiki privs 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 ask for wiki privs yourself, either to make the note or to put in a full article!)
5. 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.
6. If you'd like to do some practice work first, check out OpenHatch's Training Missions -- they'll let you practice with some of the tools you might need! (In particular, you might find their Git training mission helpful.)
7. 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 Directory Structure.
8. 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.)
9. Send in a signed Contributor Licensing Agreement, or CLA. We need to have that on file before we accept any of your contributions.
10. Pick a bug that you want to work on! You'll want to look at unclaimed issues; searches to make it easier to locate current issues are a work in progress. From time to time, people also post lists of "babydev bait" to dw_dev_training, and there is a masterlist.
11. Comment on the issue you've chosen with some variation on the word "claim" ("claim", "claimed" and "claiming" all work, and can be surrounded by any other text!)
12. 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. For a step-by-step on this, see Workflow below.
13. Commit your changes and submit them to us so that they can be integrated into the official Dreamwidth code
14. If your patch passes review, it'll be committed. If there are things that could be improved, the reviewer will comment on the commit 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.

Workflow

Most of the links in this bulleted list go to subsections of Version Control, which is a very helpful document.

1. Decide what you want to work on.
2. Make sure your git repository is up to date.
3. Create a new branch in git for this bug.
4. Make your changes, probably in your Dreamhack (editing text files, though the tricky part is finding things).
5. Restart Apache and test your changes on the Dreamhack.
6. Commit your changes to git.
7. Push your new git branch to your github account.
8. Open a pull request.
9. The request will be reviewed by a senior Dreamwidth developer, and accepted or returned for further work.

See Development and Git Getting Started for a more complete reading list, or look through the pages in Category:Development.

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!