Revision as of 16:14, 23 May 2013

Contributor Licensing Agreement

The very first thing you need to do is read and sign your CLA and mail it to Denise. If you don't agree with its terms Dreamwidth won't be able to accept your code; if you've submitted code but Denise doesn't have your CLA your code can't be added. So read it, think it over, sign it, mail it then wait until you're told it's been received. Now you can get started.

What do you need and why?

Because you're on Windows, you have to use quite a number of tools to access and manage things so this part might seem a little daunting. The good news is that 1) you're used to being flexible and resourceful, right? 2) once you've got everything set up things will be much simpler and intuitive.

So what do you need?

1. You need a github.com account to be able to fetch the Dreamwith code, copy it, and publish your patches so they can be integrated to the main code. This is both where all the Dreamwidth code comes from and where your own code will end up but it's only a gateway. You won't do much on the site itself.
2. You need a Dreamhack to see what your changes will do on the site for real. Think of a Dreamhack as an online mirror of the Dreamwidth site which you can modify.
3. You need PuTTY to connect github.com to your Dreamhack, to connect your Dreamhack to github.com, and manage your work. Think of PuTTY as your command center.
4. You need WinSCP to visualize your Dreamhack files and be able to open them in a text editor. Think of WinSCP as a Dreamhack Explorer.
5. You need a text editor to edit your files.
6. You need a Bugzilla account to find and file bugs.

Each section mentions where you need to do things so you won't get lost.

Create an account on GitHub

Go to GitHub, click on 'sign up and pricing' and create a free account. I suggest you pick a username people are familiar with. It is also best if your github username and your Bugzilla name matches.

On your GitHub account

You need to fork the Dreamwidth code onto your own account. Forking is like cloning and branching. It will copy the code and also label your copy as being a branch (a fork) of the original Dreamwidth code so that everybody knows the two are connected.

Dreamwidth is divided into two parts: an open-source part called 'dw-free', and a private part called 'dw-nonfree'. The private part is composed of elements which are specific to dreamwidth.org and can't be used on other sites (e.g. the logo) and external elements Dreamwidth is allowed to use on its own site but not redistribute to other sites.

• To fork the free part go to https://github.com/dreamwidth/dw-free and click on Fork on the upper right corner.

• To fork the nonfree part go to to https://github.com/dreamwidth/dw-nonfree and do the same.

Get a Dreamhack

Apply for a Dreamhack by filling this form. The two important fields are 'your desired username' and 'your email address'. Your username is used to manage your Dreamhack and create the URL where your Dreamhack will be located at so you can pick anything. Your email address is used to send you important information and various alerts.

N.B. Some users like having a separate adress for their dev work but it's entirely up to you!

Once you're done, you should get an email with your login username and a password. Don't lose it.

Install PuTTY

• Download 'Windows installer for everything except PuTTYtel' .exe file at PuTTY and install it.

• Run PuTTY. In the configuration window, enter "hack.dreamwidth.net" for the host name. Go to Connection/Data and enter the username/login given to you in the welcome e-mail. It should be something like dh-username.

• Click on Open. If you get a pop-up message about a key, click Yes.

• Enter the password given to you in the welcome email when asked. Note that characters aren't displayed and the cursor doesn't move. It's normal.

• Change your password by typing:

passwd

• Your default Dreamhack account is called 'system'. Set its password with this command:

$LJHOME/bin/upgrading/make_system.pl

Install WinSCP

• Install WinSCP. During the installation, you may be asked about the mode you prefer: Commander and Explorer. Commander works like an FTP client: a partitioned window with your computer files on one side and the Dreamhack files on the other. Explorer will only display your Dreamhack files and works like Windows's Explorer. Either mode is fine. Pick what you're most used to.

• Use "hack.dreamwidth.net" for the host name. Enter your username and the password you typed when you did passwd on PuTTY. Click on Save then on Login.

Get a good text editor

While you can use Notepad, I recommend Notepad++ instead. It's free, simple and will make editing much easier.

Create a Bugzilla account

Simply click here. Go to Name and Password and enter your name following this format: Name [:username]

'Name' can be your real name, a nickname, your username again, etc. Pick what you're comfortable with.

Set things up

Further configuration steps

These are not mandatory but will certainly make your life easier.

Change some git settings

In PuTTY, I suggest going through all the steps mentioned in this section.

Give special abilities to your system account

• Log in to your Dreamhack (http://www.USERNAME.hack.dreamwidth.net/) using system and your password for this account.

• Go to http://www.USERNAME.hack.dreamwidth.net/admin/priv/. Click on 'payments' type 'system' in the User field then click on 'Make Changes'. The system account now has the ability (called 'privilege' or 'priv') to give paid time to any account.

• Go to http://www.USERNAME.hack.dreamwidth.net/admin/pay. Type 'system' in the Edit user field and click on Go. Make your account a seed one.

Get rid of invite codes

• In WinSCP, go to /dw/ext/local/etc/, and double-click on config.pl. Find $USE_ACCT_CODES = 1; and change 1 to 0. Save your file.

• If you're concerned about spam, you may want to create a promo code instead. Go to http://www.USERNAME.hack.dreamwidth.net/admin/invites/promo?state=active and click on 'Create New'. Enter a code name and a number (you can edit the number later if you're about to run out of invites).

Customize PuTTY and Notepad++

See these articles for details: PuTTY, Notepad++.

Update your code

--> in PuTTY

Code is committed by developers all the time. You must always update your repositories before you do anything else.

• Go to this article and enter all the code listed in the second, bigger section for both dw-free and dw-nonfree (but don't enter the lines starting with #).

• You can also create a script to make this process simpler as explained in the article.

• Make sure to check for updates to see if the script has changed.

N.B. To create a new file open WinSCP, right click into the correct folder (/bin here) then click on New/File.

Make changes to your local code

Find or file a bug

--> in Bugzilla

• To find: you can use predefined searches such as unassigned effort-minor.

Some of these bugs may not appear to be 'minor' to you. No worries. There are usually a few tiny bugs which only require small changed to be done on one of the site pages (text to edit; elements to move, remove, add or hide from certain categories of users, etc.).

• To file: make sure it's not already been filed using simple search or advanced search then use this form to file a new bug. Fill and edit the fields as needed.

• To assign a bug to yourself, click on Take next to Assign To and set the status to IN_PROGRESS.

Create a local branch stemming from develop

Important: in PuTTY, you can get explanations about bash commands using help COMMAND (e.g. help cd) and any git commands using git COMMAND -h (e.g git pull -h).

--> in PuTTY

• Pick the correct repository:
  • if you want to work in dw-free you need to be in ~/dw$. If you're not type cd $LJHOME.
  • if you want to work in dw-nonfree you need to be in ~/dw/ext/dw-nonfree$. If you're not type cd $LJHOME/ext/dw-nonfree

• Then make sure you're in the develop branch using the checkout command:

git checkout develop

• Now you can create a new branch specifically dedicated to the bug you want to work on:

git branch BRANCH_NAME

N.B. It is best if you use the bug number and a short description as your branch name: bug####/short_description

• To switch to this branch, use the checkout command again:

git checkout BRANCH_NAME

• And that's it. Now you can start coding!

Work, work, work

--> in WinSCP and your editor

• In WinSCP right click to edit the file you want to work on.

• Remember that the free part of the code is in ~/dw/* while the non-free part is in ~/dw/ext/dw-nonfree/*.

• Site pages are either .bml or .tt files. You can find them in ~dw/htdocs/ and ~dw/views/. They may use .pm modules/widgets, found in ~dw/cgi-bin/LJ/ and ~dw/cgi-bin/DW/.

• Text strings which are not in ~dw/htdocs/xxx.bml.text and ~dw/views/xxx.tt.text are in ~dw/bin/upgrading/en.dat.

• For more specific searches, see this article on how to use rgrep and find.

Test your changes

--> on your Dreamhack

Go to your Dreamhack and test. Edit the files again in WinSCP if more changes are needed. Go through these steps again to test your new changes.

N.B. In some rare instances, you may need to update your database to see your changes.

Mark your local changes as ready to be committed

--> in PuTTY

Before being committed, work is moved to the index or staging area. Think of it as the "Ready? Steady?" before the "Go!". At this point nothing is definite and you can easily change things.

• Add your changes to the staging area:

git add FILE_NAME

• To add all files which have been updated or deleted at once:

git add -u

• To add all files which have been added, deleted or updated at once:

git add .

• If you realize you need to do some more work, edit files again and use add again when you're done. It's that simple.

Commit your changes locally

--> in PuTTY

• If you think you're done with your work at this point you can commit your changes locally:

git commit

• This will open the nano editor so you can type a commit message. Unfortunately, nano isn't very easy to type into (you can't use the number pad for instance) so I advise you to type your commit message in your text editor then paste it in nano (right click in PuTTY to paste).

• Here's an example of commit message (try and keep line shorts):

(Bug #123) Short subject

Patch description

Description can go on several short lines.

• Hit Ctrl+X, 'y' then enter to save your message.

• If you you need to do some more work later you can update your commit:

git commit --amend

N.B. You can also do this if you need to edit your commit message.

• If you want to pace yourself or be easily able to go back to a certain point in your work you can do successive commits instead of one big final one.

Go from local to global

Push the changes to your github.com repository

--> in PuTTY

You should only push your local changes to your develop branch on github.com once you're happy with your patch as things are a bit harder to change at this point. Once you've finished your work use the push command and the branch name:

git push origin BRANCH_NAME

Request your changes to be pulled into the original Dreamwidth repository

--> on github.com

Go to your profile page on GitHub. Select the Public Activity tab. Spot the line where it says you've created a new branch. Click on the branch name. Click on Compare to make sure things are how you want them to be. Once you've checked things over, click on Pull Request at the top.

N.B. If there's an unusual delay between the moment you pushed your branch and the moment it appears on GitHub, check the status page.

What now?

--> in Bugzilla

• You'll get an email notification once your changes have been accepted and pulled into the Dreamwidth code (i.e. merged into the original develop branch), and the bug will be closed if no more work is needed.

--> on github.com

• On GitHub your request will be marked as merged on your profile page.

• That's it! You're done. Congratulations!

Extra case: the release branch

--> in PuTTY

If you need to make urgent fixes after a code push, first create a copy of the release branch. Like so:

git checkout -b release-X.X dreamwidth/release-X.X

X-X is the number given to the release on the GitHub repo branch. Make sure it matches.

Then follow the usual steps (edit, add, commit, push) and when you request your changes to be pulled on GitHub make sure to select the release branch as your base branch and your head branch.

Help! Troubleshooting tips

My branch has commits from another user!

--> in PuTTY

If you realize once you've pushed your branch to github.com that you built it upon another pull request that has been merged since then and that your branch now has commits from another user, don't panic. If these commits don't affect yours, you can easily rebase your branch against develop as explained in this how to. The system will see that some of the commits on your branch have already been merged into develop and will skip them, thus leaving only your own unmerged commits on your branch. There, all clean! All you have to do is push your branch again.

Issues with text strings

• As denise explained here, you need to delete old text strings and create new ones when you edit .text files or en.dat instead of simply editing the text. If the change isn't critical - the string doesn't need to be renamed or the text change is minor - it's better to notify the site copy team so that text can be changed locally and the original file left alone.

• If text you've modified doesn't appear on the site after a code push, append ?uselang=debug to the page URL to make sure it's using the right string. If it is and it still doesn't display after a while, comment on dw_maintenance.

Starting over

If something's wrong you can:

• delete your GitHub repositories on github.com: go to your repository, click on Admin then scroll down to 'Delete this repository'.
• then go through these steps again.

If something's *really* wrong you can also rebuild you Dreamhack completely and start over from scratch.

Going further / References

To understand things better, I suggest reading relevant sections of Git - The Simple Guide, watching part of Git for Ages 4 and Up (Watch on YouTube or Download), and reading the first three chapters of Pro Git.

For lots of useful commands, see these how-tos.

Other useful references:

• Moving to GitHub
• Development Maintenance
• Github Development Process
• Bash commands
• Git: Getting Started
• Pro Git
• Pro Git - Index of Commands
• Git Reference
• Mark's instructions on Bugzilla usernames.