Difference between revisions of "Beginning dev checklist"

From Dreamwidth Notes
Jump to: navigation, search
m (....correctly this time)
(start of sectioning)
Line 5: Line 5:
 
If you're interested in beginning development with us, we'll teach you. Here's the absolute basic framework of what you need to know, what you need to have, and what you need to learn. We'll fill it in with links to Wiki articles explaining each step of the process.
 
If you're interested in beginning development with us, we'll teach you. Here's the absolute basic framework of what you need to know, what you need to have, and what you need to learn. We'll fill it in with links to Wiki articles explaining each step of the process.
  
* The absolute first thing you'll need is a development environment: someplace where you can host the code you're going to be working on. This will be a complete local installation of the Dreamwidth service, running on a separate server. If you're comfortable with installing the code yourself, see [[Dev Getting Started]]. If you absolutely don't know where to start, are overwhelmed at the idea of trying, we offer hosted development installations on our [http://hack.dreamwidth.net Dreamhack] service: we'll do the initial install for you. (You'll have to keep it upgraded after that.)
+
== Setting up and working with a development environment ==
  
* The Dreamwidth code runs under Unix (specifically, Ubuntu Linux). If you've never used Unix before, you might want to read over [http://www.ee.surrey.ac.uk/Teaching/Unix/ a tutorial] on how to approach the system, how to use the command line, how to create files, delete files, move files, and other useful things. For the rest of this list, I'll assume you're familiar with the basics of directory structures. In particular, you use the symbol ~ to represent your home directory: the top-level directory that everything else goes in.
+
=== Getting a development environment ===
  
* Some instructions on the wiki will mention $LJHOME (must be all caps). This is where your Dreamwidth code can be found. You can use it as-is; it points to ~/dw. For example, cd $LJHOME/... is the same as cd ~/dw/..., and will change your directory to ~/dw/...
+
The absolute first thing you'll need is a development environment: someplace where you can host the code you're going to be working on. This will be a complete local installation of the Dreamwidth service, running on a separate server. If you're comfortable with installing the code yourself, see [[Dev Getting Started]]. If you absolutely don't know where to start, are overwhelmed at the idea of trying, we offer hosted development installations on our [http://hack.dreamwidth.net Dreamhack] service: we'll do the initial install for you. (You'll have to keep it upgraded after that.)
  
* Once you have a Dreamhack, you'll need to access the files on them (in order to change them). This involves downloading a program that will do SSH, or "secure shell". It lets you connect to the other site (in this case your Dreamhack) and work with the files, which you can't do through your browser. If you're running Windows, download [http://www.chiark.greenend.org.uk/~sgtatham/putty/ PuTTY]. If you're on a Mac or a Linux distribution, you won't need a separate program; the Terminal (Applications/Utilities/Terminal) will let you connect.
+
=== Working with Unix ===
  
* Once you have an SSH client, you can connect to Dreamhack. In PuTTY, put "hack.dreamwidth.net" for the server, and use the username and password you were given in your welcome email. In Terminal, type:
+
The Dreamwidth code runs under Unix (specifically, Ubuntu Linux). If you've never used Unix before, you might want to read over [http://www.ee.surrey.ac.uk/Teaching/Unix/ a tutorial] on how to approach the system, how to use the command line, how to create files, delete files, move files, and other useful things. For the rest of this list, I'll assume you're familiar with the basics of directory structures. In particular, you use the symbol ~ to represent your home directory: the top-level directory that everything else goes in.
 +
 
 +
=== The location of $LJHOME ===
 +
 
 +
Some instructions on the wiki will mention $LJHOME (must be all caps). This is where your Dreamwidth code can be found. You can use it as-is; it points to ~/dw. For example, cd $LJHOME/... is the same as cd ~/dw/..., and will change your directory to ~/dw/...
 +
 
 +
=== Accessing your files ===
 +
 
 +
Once you have a Dreamhack, you'll need to access the files on them (in order to change them). This involves downloading a program that will do SSH, or "secure shell". It lets you connect to the other site (in this case your Dreamhack) and work with the files, which you can't do through your browser. If you're running Windows, download [http://www.chiark.greenend.org.uk/~sgtatham/putty/ PuTTY]. If you're on a Mac or a Linux distribution, you won't need a separate program; the Terminal (Applications/Utilities/Terminal) will let you connect.
 +
 
 +
=== Connecting to your development environment ===
 +
 
 +
Once you have an SSH client, you can connect to Dreamhack. In PuTTY, put "hack.dreamwidth.net" for the server, and use the username and password you were given in your welcome email. In Terminal, type:
  
 
<source lang="bash">ssh dh-username@hack.dreamwidth.net</source>
 
<source lang="bash">ssh dh-username@hack.dreamwidth.net</source>
  
* The first time you log in, you'll probably want to change your password. Type:
+
The first time you log in, you'll probably want to change your password. Type:
  
 
<source lang="bash">passwd</source>
 
<source lang="bash">passwd</source>
  
* You'll also need to set the LJ system password. Type:
+
You'll also need to set the LJ system password. Type:
  
 
<source lang="bash">$LJHOME/bin/upgrading/make_system.pl</source>
 
<source lang="bash">$LJHOME/bin/upgrading/make_system.pl</source>
  
* When you're ready, start Apache. Type:
+
When you're ready, start Apache. Type:
  
 
<source lang="bash">start-apache</source>
 
<source lang="bash">start-apache</source>
Line 31: Line 43:
 
( ... insert other on-first-login tasks here, like make-system.pl )
 
( ... insert other on-first-login tasks here, like make-system.pl )
  
* Once you've done all that, you're ready to start programming! You're going to need an editor: something that will let you edit the files you're working with. There are two ways you can do this. You can either download the files from Dreamhack to your local machine, edit them, and then re-upload them, or you can edit them directly on Dreamhack itself. If you want to edit them on Dreamhack itself, you're going to need to learn one of the Unix editors. The question of <em>which</em> editor you should be using is going to be personal preference, and the "editor war" is a hotly-debated topic. For an absolute beginner, I believe the best editor to use is pico/nano; it doesn't have everything, but it is very, <em>very</em> quickly learnable.
+
== Start programming ==
  
* One thing you absolutely do need to keep in mind, though, is that by default pico quietly adds linebreaks to the file that you're working on, not just word-wraps it for display in the editor. This can cause trouble with generating patches, and because it's indistinguishable from word-wrapping in the editor, it can take you a while to diagnose it. To prevent this from happening, when you call pico, do it with the -w flag, which will turn off auto-linebreaking:
+
=== Editors ===
 +
 
 +
Once you've done all that, you're ready to start programming! You're going to need an editor: something that will let you edit the files you're working with. There are two ways you can do this. You can either download the files from Dreamhack to your local machine, edit them, and then re-upload them, or you can edit them directly on Dreamhack itself. If you want to edit them on Dreamhack itself, you're going to need to learn one of the Unix editors. The question of <em>which</em> editor you should be using is going to be personal preference, and the "editor war" is a hotly-debated topic. For an absolute beginner, I believe the best editor to use is pico/nano; it doesn't have everything, but it is very, <em>very</em> quickly learnable.
 +
 
 +
=== Working with pico ===
 +
 
 +
{{Note|text=Shouldn't we actually be talking about nano? --[[User:Foxfirefey|Foxfirefey]] 05:08, 7 April 2009 (UTC)}}
 +
 
 +
One thing you absolutely do need to keep in mind, though, is that by default pico quietly adds linebreaks to the file that you're working on, not just word-wraps it for display in the editor. This can cause trouble with generating patches, and because it's indistinguishable from word-wrapping in the editor, it can take you a while to diagnose it. To prevent this from happening, when you call pico, do it with the -w flag, which will turn off auto-linebreaking:
  
 
<source lang="bash">pico -w filename</source>
 
<source lang="bash">pico -w filename</source>
  
* A useful first edit is to turn invite codes off in etc/config.pl, to make it quicker to set up dummy accounts for playing around. Type:
+
=== Allow users to register without invite codes ===
 +
 
 +
{{Note|text=Maybe should reorganize this so this is closer up to the first setups?}}
 +
 
 +
A useful first edit is to turn invite codes off in etc/config.pl, to make it quicker to set up dummy accounts for playing around. Type:
  
 
<source lang="bash">cd $LJHOME
 
<source lang="bash">cd $LJHOME
Line 46: Line 70:
 
( ... insert how-to-edit-a-file here )
 
( ... insert how-to-edit-a-file here )
  
* Your Dreamwidth code directory is set up with two separate copies of the code: one that actually runs the site (in ~/dw/*) and one that is in your 'cvs' directory (~/dw/cvs/dw-free or ~/dw/cvs/dw-nonfree), which is what  you use to sync back and forth with the 'official' copy of the code. (Think of the whole thing like an endless series of comparisons: you're comparing the version you're working on with the version you have set aside, which you <em>then</em> compare against the master version that's stored on our code repository.)
+
=== Layout of the code directory ===
  
* Which version you edit is up to you. Everyone does it a bit differently. You can either edit in the live directory structure (~/dw/*) and then copy over to the cvs directory (~/dw/cvs/dw-free), or edit in the cvs directory and then copy over to the live directory. Either way, you're going to need to have your changes in both places: you need to have them in the live directory so you can test your change in your browser, and you need to have them in the cvs directory so you can generate a patchfile (which is a file that anyone else can apply against the code to make the same changes you're making).
+
Your Dreamwidth code directory is set up with two separate copies of the code: one that actually runs the site (in ~/dw/*) and one that is in your 'cvs' directory (~/dw/cvs/dw-free or ~/dw/cvs/dw-nonfree), which is what  you use to sync back and forth with the 'official' copy of the code. (Think of the whole thing like an endless series of comparisons: you're comparing the version you're working on with the version you have set aside, which you <em>then</em> compare against the master version that's stored on our code repository.)
 +
 
 +
Which version you edit is up to you. Everyone does it a bit differently. You can either edit in the live directory structure (~/dw/*) and then copy over to the cvs directory (~/dw/cvs/dw-free), or edit in the cvs directory and then copy over to the live directory. Either way, you're going to need to have your changes in both places: you need to have them in the live directory so you can test your change in your browser, and you need to have them in the cvs directory so you can generate a patchfile (which is a file that anyone else can apply against the code to make the same changes you're making).
  
 
( ... insert more background information on version control, patch files, diffs, copying over, and provide step-by-step list of what each workflow consists of, its benefits, and its drawbacks )
 
( ... insert more background information on version control, patch files, diffs, copying over, and provide step-by-step list of what each workflow consists of, its benefits, and its drawbacks )
  
* The code is a little ... sprawling. Finding what you're looking to change can be pretty hard. Fortunately, we have some instructions at [[Dev Finding Things]].
+
=== Finding what you're looking for in the code ===
 +
 
 +
The code is a little ... sprawling. Finding what you're looking to change can be pretty hard. Fortunately, we have some instructions at [[Dev Finding Things]].
  
 
( ...insert more about where to look for things, common use areas, how to use rgrep for fun and profit, etc )  
 
( ...insert more about where to look for things, common use areas, how to use rgrep for fun and profit, etc )  
Line 58: Line 86:
 
( ...insert more about how to recover from a disaster, aka What Happens When You Break It )
 
( ...insert more about how to recover from a disaster, aka What Happens When You Break It )
  
* Once you've made your changes, and verified that they're working the way you want them to &mdash; testing every single usage case you think could possibly be affected by what you've changed &mdash;
+
== Submitting your changes to Dreamwidth ==
you need to submit your change to Bugzilla, so it can be applied to the official code repository. You <em>don't</em> send the whole file; you're going to generate what's known as a "patch" file, which highlights the bits that you've changed and only the bits that you've changed. One of the people (known as a 'committer') who maintain the official code repository will apply that patch to their own development environment, verify that it works, and if it works, commit it to the main code repository.
+
  
* You don't have to manually write the patch file. There are tools that will create them for you. Again, everyone's workflow is slightly different, and there are a few different ways to generate patch files.
+
=== Making your changes into a patch ===
 +
 
 +
Once you've made your changes, and verified that they're working the way you want them to &mdash; testing every single usage case you think could possibly be affected by what you've changed &mdash; you need to submit your change to [[Bugzilla]], so it can be applied to the official code repository. You <em>don't</em> send the whole file; you're going to generate what's known as a "patch" file, which highlights the bits that you've changed and only the bits that you've changed. One of the people (known as a 'committer') who maintain the official code repository will apply that patch to their own development environment, verify that it works, and if it works, commit it to the main code repository.
 +
 
 +
You don't have to manually write the patch file. There are tools that will create them for you. Again, everyone's workflow is slightly different, and there are a few different ways to generate patch files.
  
 
( ...insert more about how to generate a patch file here )
 
( ...insert more about how to generate a patch file here )
  
* Once you've got your patch file, you will upload it to Bugzilla. See [[Bugzilla workflow]] for the basics of how to get your patch file into Bugzilla and how you need to handle it.
+
=== Uploading your patch to Bugzilla ===
 +
 
 +
Once you've got your patch file, you will upload it to Bugzilla. See [[Bugzilla workflow]] for the basics of how to get your patch file into Bugzilla and how you need to handle it.
  
 
* And that's it!
 
* And that's it!

Revision as of 05:08, 7 April 2009

Expand: See inline expansion notes.

We believe that our mentoring process is an investment in our future and in the future of Open Source. By teaching people -- no matter how experienced or inexperienced -- how to contribute to our codebase, we're building our own next generation of contributors. Every hour that we spend training someone to contribute is paid back tenfold, in multiple ways: we get more patches submitted, we get more people who can mentor other people, we get better documentation, and we get more people into the Open Source world.

If you're interested in beginning development with us, we'll teach you. Here's the absolute basic framework of what you need to know, what you need to have, and what you need to learn. We'll fill it in with links to Wiki articles explaining each step of the process.

Setting up and working with a development environment

Getting a development environment

The absolute first thing you'll need is a development environment: someplace where you can host the code you're going to be working on. This will be a complete local installation of the Dreamwidth service, running on a separate server. If you're comfortable with installing the code yourself, see Dev Getting Started. If you absolutely don't know where to start, are overwhelmed at the idea of trying, we offer hosted development installations on our Dreamhack service: we'll do the initial install for you. (You'll have to keep it upgraded after that.)

Working with Unix

The Dreamwidth code runs under Unix (specifically, Ubuntu Linux). If you've never used Unix before, you might want to read over a tutorial on how to approach the system, how to use the command line, how to create files, delete files, move files, and other useful things. For the rest of this list, I'll assume you're familiar with the basics of directory structures. In particular, you use the symbol ~ to represent your home directory: the top-level directory that everything else goes in.

The location of $LJHOME

Some instructions on the wiki will mention $LJHOME (must be all caps). This is where your Dreamwidth code can be found. You can use it as-is; it points to ~/dw. For example, cd $LJHOME/... is the same as cd ~/dw/..., and will change your directory to ~/dw/...

Accessing your files

Once you have a Dreamhack, you'll need to access the files on them (in order to change them). This involves downloading a program that will do SSH, or "secure shell". It lets you connect to the other site (in this case your Dreamhack) and work with the files, which you can't do through your browser. If you're running Windows, download PuTTY. If you're on a Mac or a Linux distribution, you won't need a separate program; the Terminal (Applications/Utilities/Terminal) will let you connect.

Connecting to your development environment

Once you have an SSH client, you can connect to Dreamhack. In PuTTY, put "hack.dreamwidth.net" for the server, and use the username and password you were given in your welcome email. In Terminal, type:

ssh dh-username@hack.dreamwidth.net

The first time you log in, you'll probably want to change your password. Type:

passwd

You'll also need to set the LJ system password. Type:

$LJHOME/bin/upgrading/make_system.pl

When you're ready, start Apache. Type:

start-apache

( ... insert other on-first-login tasks here, like make-system.pl )

Start programming

Editors

Once you've done all that, you're ready to start programming! You're going to need an editor: something that will let you edit the files you're working with. There are two ways you can do this. You can either download the files from Dreamhack to your local machine, edit them, and then re-upload them, or you can edit them directly on Dreamhack itself. If you want to edit them on Dreamhack itself, you're going to need to learn one of the Unix editors. The question of which editor you should be using is going to be personal preference, and the "editor war" is a hotly-debated topic. For an absolute beginner, I believe the best editor to use is pico/nano; it doesn't have everything, but it is very, very quickly learnable.

Working with pico

Note: Shouldn't we actually be talking about nano? --Foxfirefey 05:08, 7 April 2009 (UTC)

One thing you absolutely do need to keep in mind, though, is that by default pico quietly adds linebreaks to the file that you're working on, not just word-wraps it for display in the editor. This can cause trouble with generating patches, and because it's indistinguishable from word-wrapping in the editor, it can take you a while to diagnose it. To prevent this from happening, when you call pico, do it with the -w flag, which will turn off auto-linebreaking:

pico -w filename

Allow users to register without invite codes

Note: Maybe should reorganize this so this is closer up to the first setups?

A useful first edit is to turn invite codes off in etc/config.pl, to make it quicker to set up dummy accounts for playing around. Type:

cd $LJHOME
pico -w etc/config.pl

This will open the config file in pico. Have a skim through, as there are lots of useful options here. To turn invite codes off, scroll down to $USE_ACCT_CODES = 1 and change it to 0. To save this, use Ctrl-O and then Enter, and exit using Ctrl-X. You can then go to http://www.yourname.hack.dreamwidth.net and start playing.

( ... insert how-to-edit-a-file here )

Layout of the code directory

Your Dreamwidth code directory is set up with two separate copies of the code: one that actually runs the site (in ~/dw/*) and one that is in your 'cvs' directory (~/dw/cvs/dw-free or ~/dw/cvs/dw-nonfree), which is what you use to sync back and forth with the 'official' copy of the code. (Think of the whole thing like an endless series of comparisons: you're comparing the version you're working on with the version you have set aside, which you then compare against the master version that's stored on our code repository.)

Which version you edit is up to you. Everyone does it a bit differently. You can either edit in the live directory structure (~/dw/*) and then copy over to the cvs directory (~/dw/cvs/dw-free), or edit in the cvs directory and then copy over to the live directory. Either way, you're going to need to have your changes in both places: you need to have them in the live directory so you can test your change in your browser, and you need to have them in the cvs directory so you can generate a patchfile (which is a file that anyone else can apply against the code to make the same changes you're making).

( ... insert more background information on version control, patch files, diffs, copying over, and provide step-by-step list of what each workflow consists of, its benefits, and its drawbacks )

Finding what you're looking for in the code

The code is a little ... sprawling. Finding what you're looking to change can be pretty hard. Fortunately, we have some instructions at Dev Finding Things.

( ...insert more about where to look for things, common use areas, how to use rgrep for fun and profit, etc )

( ...insert more about how to recover from a disaster, aka What Happens When You Break It )

Submitting your changes to Dreamwidth

Making your changes into a patch

Once you've made your changes, and verified that they're working the way you want them to — testing every single usage case you think could possibly be affected by what you've changed — you need to submit your change to Bugzilla, so it can be applied to the official code repository. You don't send the whole file; you're going to generate what's known as a "patch" file, which highlights the bits that you've changed and only the bits that you've changed. One of the people (known as a 'committer') who maintain the official code repository will apply that patch to their own development environment, verify that it works, and if it works, commit it to the main code repository.

You don't have to manually write the patch file. There are tools that will create them for you. Again, everyone's workflow is slightly different, and there are a few different ways to generate patch files.

( ...insert more about how to generate a patch file here )

Uploading your patch to Bugzilla

Once you've got your patch file, you will upload it to Bugzilla. See Bugzilla workflow for the basics of how to get your patch file into Bugzilla and how you need to handle it.

  • And that's it!