|
|
| (159 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| − | {{Note|text=I'm a newbie. I'm editing this as I'm learning new things or better ways to do what I know how to do. Feel free to suggest, correct, expand, add, anything that could make this better and clearer. ^_^}}
| + | #REDIRECT [[Newbie_Guide:_Getting_Started_on_Windows]] |
| − | | + | |
| − | | + | |
| − | = Install and Set Things Up =
| + | |
| − | | + | |
| − | This may seem like a lot of things to do before you can really get started, things you're probably not familiar with but 1) you can do it 2) you'll only have to do this once.
| + | |
| − | | + | |
| − | | + | |
| − | == Get a Dreamhack ==
| + | |
| − | | + | |
| − | What's a Dreamhack? To put it simply, it's an online mirror of the Dreamwidth site which is set up for any developer, beginner or experienced, who asks for it. This way, you don't have to go through the complicated process of installing the Dreamwidth code on your computer.
| + | |
| − | | + | |
| − | * Apply for a Dreamhack by [http://hack.dreamwidth.net/apply.shtml filling this form]. The two important fields are 'Your Desired Username' and 'Your email address'. Note that your username is the name you'll use to log in to your Dreamhack; it's not the name of your account over there so no need to agonize over it. ;) Your e-mail address is used to send you a welcome e-mail which contains important information as well as maintenance/issue alerts and reinstall e-mails if you need to reinstall so it does matter. Also, some people like having an e-mail account specifically devoted to development. It's up to you.
| + | |
| − | | + | |
| − | * Once you're done, you should get an e-mail with your login username and a password. Don't lose it. Once you've gotten this e-mail, you need to install two programs to be able to manage your Dreamhack: [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY] and [http://winscp.net/eng/download.php WinSCP].
| + | |
| − | | + | |
| − | | + | |
| − | == Install PuTTY ==
| + | |
| − | | + | |
| − | What for? PuTTY will allow you to start and stop your Dreamhack, update it when changes are made (either by you or other developers) and generate patches.
| + | |
| − | | + | |
| − | * Download [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY] - choose the 'Windows installer for everything except PuTTYtel' .exe file - 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 e-mail when asked. Note that no characters are displayed and the cursor won't move. It's normal.
| + | |
| − | | + | |
| − | * Change your password by typing: <source lang="bash">passwd</source>
| + | |
| − | | + | |
| − | * And that's it for now. :)
| + | |
| − | | + | |
| − | | + | |
| − | == Install WinSCP ==
| + | |
| − | | + | |
| − | What for? WinSCP will allow you to browse and edit your Dreamhack files.
| + | |
| − | | + | |
| − | * Install [http://winscp.net/eng/download.php 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. I prefer this mode because I don't need to access any files on my computer but choose what's best for you.
| + | |
| − | | + | |
| − | * Use "hack.dreamwidth.net" for the host name. Enter your username and password (the new one!). Click on Save then on Login.
| + | |
| − | | + | |
| − | | + | |
| − | == Set Up Your Dreamhack ==
| + | |
| − | | + | |
| − | === Protect Your Config Files ===
| + | |
| − | | + | |
| − | * Follow the steps outlined at [[Dreamhack_getting_started#Back_up_your_configs|Back Up Your Configs]]. This will make sure you always have clean copies of your config files in /config-backup.
| + | |
| − | | + | |
| − | : Go to PuTTY and copy paste the code given to you in the box.
| + | |
| − | | + | |
| − | * Follow the steps outlined at [[Dreamhack_getting_started#Protect_your_configs_from_updates|Protect your configs from updates]]. This will create new folders with copies of you config files so that you can safely edit them.
| + | |
| − | | + | |
| − | : Go to PuTTY and copy paste the code given to you.
| + | |
| − | : Go to WinSCP, to <code>/dw/cvs/local/cvs/</code>.
| + | |
| − | : In the right-sided window, right-click and select New/File. Call it <code>multicvs-private.conf</code>. Type the code given to you in the second box then save.
| + | |
| − | : Go back to PuTTY and copy/paste the code given to you in the third box.
| + | |
| − | | + | |
| − | | + | |
| − | === Create Scripts for Routine Tasks ===
| + | |
| − | | + | |
| − | * Create the <em>dwu</em>, <em>dws</em> and <em>dwdb</em> scripts as explained in [[Dev_Maintenance#Scripting|Scripting]]. U is for update, S is for Synchronize, DB is for Database.
| + | |
| − | | + | |
| − | : Go to WinSCP and create the three files in <code>/bin</code> (again by right-clicking) with the code given to you in the boxes. For dwu, use the code from the second box.
| + | |
| − | : Go to PuTTY and make them executable using the <code>chmod ugo+x</code> command. The code you need to type is bolded and is above each box of code.
| + | |
| − | | + | |
| − | | + | |
| − | === Manage Your System Account ===
| + | |
| − | | + | |
| − | * Your default Dreamhack account is called system. Go to PuTTY and type this to set its password: <source lang="bash">$LJHOME/bin/upgrading/make_system.pl</source>
| + | |
| − | | + | |
| − | * Log in to your Dreamhack (http://www.yourusername.hack.dreamwidth.net/) using system and your new password.
| + | |
| − | ;
| + | |
| − | * Go to [http://www.yourusername.hack.dreamwidth.net/admin/priv/ http://www.yourusername.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 (privilege) to give paid time to any account.
| + | |
| − | | + | |
| − | * Go to [http://www.yourusername.hack.dreamwidth.net/admin/pay http://www.yourusername.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 ===
| + | |
| − | | + | |
| − | * Go to WinSCP, to <code>/dw/cvs/local/etc/</code>, and double-click on <code>config.pl</code>. Find <code>$USE_ACCT_CODES = 1;</code> and change 1 to <code>0</code>. Save your file.
| + | |
| − | | + | |
| − | * Go to PuTTY and type this to make the changes go live on your Dreamhack:
| + | |
| − | <source lang="bash">cd $LJHOME
| + | |
| − | stop-apache
| + | |
| − | dws
| + | |
| − | dwdb
| + | |
| − | start-apache</source>
| + | |
| − | | + | |
| − | | + | |
| − | == Create a Bugzilla account ==
| + | |
| − | | + | |
| − | * Simply [http://bugs.dwscoalition.org/createaccount.cgi click here].
| + | |
| − | | + | |
| − | * As <dwuser>mark</dwuser> explained [http://dw-dev.dreamwidth.org/17146.html here], go to [http://bugs.dwscoalition.org/userprefs.cgi?tab=account Name and Password] and enter your name following this format: <code>Name [:username]</code>. 'Name' can be your real-like name, a nickname, your username or any name you want. You don't have to enter your real name if you don't want to.
| + | |
| − | | + | |
| − | | + | |
| − | == Finish Setting Up Your Dreamhack ==
| + | |
| − | | + | |
| − | * The final and last step is to create files and folders for patches.
| + | |
| − | | + | |
| − | * In PuTTY, type this to create files and folders in <code>~/dw/csv/dw-free/.hg/</code>:
| + | |
| − | <source lang="bash">cd $LJHOME/cvs/dw-free
| + | |
| − | hg qinit -c</source>
| + | |
| − | | + | |
| − | * In WinSCP, open <code>~/dw/csv/dw-free/.hg/hgrc</code> and add this:
| + | |
| − | <source lang="perl">[ui]
| + | |
| − | username = username <username@gmail.com></source>
| + | |
| − | | + | |
| − | * Change the second username to your Bugzilla name and the e-mail address to your Bugzilla adress. Save the file.
| + | |
| − | | + | |
| − | * In PuTTY again, type this to create files and folders in <code>~/dw/csv/dw-nonfree/.hg/</code>:
| + | |
| − | <source lang="bash">cd $LJHOME/cvs/dw-nonfree
| + | |
| − | hg qinit -c</source>
| + | |
| − | | + | |
| − | * In WinSCP, open <code>~/dw/csv/dw-nonfree/.hg/hgrc</code> and add this:
| + | |
| − | <source lang="perl">[ui]
| + | |
| − | username = username <username@gmail.com></source>
| + | |
| − | | + | |
| − | * Change the second username to your Bugzilla name and the e-mail address to your Bugzilla adress. Save the file.
| + | |
| − | | + | |
| − | | + | |
| − | = How All of This Works =
| + | |
| − | | + | |
| − | * Your Dreamhack has two parts:
| + | |
| − | ** the live part (<code>~/dw/*</code>)
| + | |
| − | ** two main repository parts (<code>~/dw/cvs/dw-free/*</code> and <code>~/dw/cvs/dw-nonfree/*</code>).
| + | |
| − | | + | |
| − | * What you see on [http://www.yourusername.hack.dreamwidth.net/ http://www.yourusername.hack.dreamwidth.net/] is the live part.
| + | |
| − | | + | |
| − | * But you work with the repositories: you edit repository files and you create patches in repository folders.
| + | |
| − | | + | |
| − | * To test your changes, you need to make the live part match the repository parts. To do that, you use the 'synchronize' and 'update database' scripts you've created earlier:
| + | |
| − | <source lang="bash">cd $LJHOME
| + | |
| − | stop-apache
| + | |
| − | dws
| + | |
| − | dwdb
| + | |
| − | start-apache</source>
| + | |
| − | | + | |
| − | * Code is committed by developers all the time. You must regularly update your repositories by running the 'update' script:
| + | |
| − | <source lang="bash">cd $LJHOME
| + | |
| − | stop-apache
| + | |
| − | dwu
| + | |
| − | start-apache</source>
| + | |
| − | | + | |
| − | Of course, you'll have to run <code>dws</code> and <code>dwdb</code> again after that to make your Dreamhack code be up-to-date as well. You'll do this sequence very often. :)
| + | |
| − | | + | |
| − | * You use PuTTY to update your Dreamhack code, create patches and manage patches.
| + | |
| − | | + | |
| − | * You use WinSCP to edit Dreamhack files.
| + | |
| − | | + | |
| − | * You use Bugzilla to find bugs, file bugs, and upload patches.
| + | |
| − | | + | |
| − | | + | |
| − | = Before You Fix Anything =
| + | |
| − | | + | |
| − | | + | |
| − | == Find or File a Bug ==
| + | |
| − | | + | |
| − | * To find: you can use [http://bugs.dwscoalition.org/userprefs.cgi?tab=saved-searches predefined searches] such as [http://bugs.dwscoalition.org/buglist.cgi?cmdtype=dorem&remaction=run&namedcmd=unassigned%20effort-minor&sharer_id=2 unassigned effort-minor].
| + | |
| − | | + | |
| − | : Some of these bugs won't appear to require 'minor' effort to you. It's normal. Try to find small bugs among them: minor modifications to be done on one of the site pages (text to be modified; elements to be added, removed or moved; elements to be hidden from some categories of users, etc.).
| + | |
| − | | + | |
| − | * To file: make sure it's not already been filed using [http://bugs.dwscoalition.org/query.cgi?format=specific simple search] or [http://bugs.dwscoalition.org/query.cgi?format=advanced advanced search] then [http://bugs.dwscoalition.org/enter_bug.cgi?product=Dreamwidth%20Development use this form] to file a new bug. Fill and edit the fields as needed and don't forget to enter your e-mail address in Assign To and set the status to Assigned if you want to fix it. It's also ok to file a bug you know you're not going to be able to fix. Just leave it as New.
| + | |
| − | | + | |
| − | | + | |
| − | == Create a Patch ==
| + | |
| − | | + | |
| − | * First make sure nobody's working on the files you want to edit. If there are already patches up for review/commit, you may need to first [[#Import a Patch|import and apply these patches to your Dreamhack]] to avoid conflicts. You can see patches up for commit by [http://bugs.dwscoalition.org/buglist.cgi?cmdtype=dorem&remaction=run&namedcmd=needs-commit&sharer_id=2 clicking here]. You can also wait for them to be committed if you don't want to go to the trouble of importing other patches. There's no rush. :)
| + | |
| − | | + | |
| − | * Open PuTTY and update everything. You need to work with the latest code.
| + | |
| − | | + | |
| − | * Go to dw-free by typing this then Enter:
| + | |
| − | <source lang="bash">cd $LJHOME
| + | |
| − | tocvs</source>
| + | |
| − | | + | |
| − | : To go to dw-nonfree, type this then Enter:
| + | |
| − | <source lang="bash">cd $LJHOME
| + | |
| − | tocvs n</source>
| + | |
| − | | + | |
| − | * Create a new patch by typing this then Enter (change NUMBER and PATCHNAME of course):
| + | |
| − | <source lang="bash">hg qnew -g bugNUMBER_PATCHNAME.diff</source>
| + | |
| − | | + | |
| − | | + | |
| − | == Import a Patch ==
| + | |
| − | | + | |
| − | * Go to [http://bugs.dwscoalition.org/ Bugzilla], open the bug, click on the patch. Copy its URL.
| + | |
| − | | + | |
| − | * In PuTTY, go to dw-free:
| + | |
| − | <source lang="bash">cd $LJHOME</source>
| + | |
| − | | + | |
| − | * Create a new patch (as explained [[#Create a Patch|above]]).
| + | |
| − | | + | |
| − | * Import the patch:
| + | |
| − | <source lang="bash">wget -O imported_patch URL</source>
| + | |
| − | | + | |
| − | : This will put the patch in <code>~/dw/</code> and name it 'imported_patch'.
| + | |
| − | | + | |
| − | * Type this to apply the patch:
| + | |
| − | <source lang="bash">patch -p1 < imported_patch</source>
| + | |
| − | | + | |
| − | * Type <code>hg addremove</code> if this patch adds or delete files.
| + | |
| − | | + | |
| − | * Type <code>hg qrefresh</code> to incorporate the changes into your own patch.
| + | |
| − | | + | |
| − | * Synchronize your live code and update your database (as explained [[#How All of This Works|above]]).
| + | |
| − | | + | |
| − | | + | |
| − | = Edit Files =
| + | |
| − | | + | |
| − | Use WinSCP to open the file(s) you need to edit.
| + | |
| − | | + | |
| − | * If you're working on site pages, you're working on .bml files. These are in <code>~dw/cvs/dw-free/htdocs/</code> or one of the subsequent folders. You'll see that their names correspond to the URLs of site pages. These files may use .pm modules/widgets which are in <code>~dw/cvs/dw-free/cgi-bin/DW/</code> or <code>~dw/cvs/dw-free/cgi-bin/LJ/</code>.
| + | |
| − | | + | |
| − | * If you're working on styles, your files is in [[#Where are Style Files?|one of these folders]].
| + | |
| − | | + | |
| − | * For text strings which are not in <code>~dw/cvs/dw-free/htdocs/</code> .bml.text files, see <code>~dw/cvs/dw-free/bin/upgrading/en.dat</code>.
| + | |
| − | | + | |
| − | * For more specific searches, you can use the grep command: <code>grep [option(s)] pattern [file(s)]</code>
| + | |
| − | | + | |
| − | Interesting Options:
| + | |
| − | | + | |
| − | -E: match using extended regular expressions
| + | |
| − | | + | |
| − | -F: match using fixed strings
| + | |
| − | | + | |
| − | -r: recursive
| + | |
| − | | + | |
| − | -i: case insensitive
| + | |
| − | | + | |
| − | -l: filename only
| + | |
| − | | + | |
| − | -n: add relative line number
| + | |
| − | | + | |
| − | Examples:
| + | |
| − | | + | |
| − | <source lang="bash">grep -ri "find this text" * | more</source>
| + | |
| − | | + | |
| − | : This will search for "find this text" in all files.
| + | |
| − | | + | |
| − | <source lang="bash">grep -rl print_entry $LJHOME/bin/upgrading/s2layers</source>
| + | |
| − | | + | |
| − | : This will search for files containing "print_entry" in the /s2layers folder.
| + | |
| − | | + | |
| − | * If WinSCP is not using your favorite editor, go to View/Preferences/Editor. Click on Add/External Editor and Browse. At the end don't forget to click on Up to make it the default editor.
| + | |
| − | | + | |
| − | = Test Your Changes on Your Dreamhack =
| + | |
| − | | + | |
| − | * In PuTTY, stop your Dreamhack:
| + | |
| − | <source lang="bash">cd $LJHOME
| + | |
| − | stop-apache</source>
| + | |
| − | | + | |
| − | * Synchronize your live code and update your database:
| + | |
| − | <source lang="bash">dws
| + | |
| − | dwdb</source>
| + | |
| − | | + | |
| − | * Start your Dreamhack again:
| + | |
| − | <source lang="bash">start-apache</source>
| + | |
| − | | + | |
| − | * 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.
| + | |
| − | | + | |
| − | | + | |
| − | = Upload Your Patch =
| + | |
| − | | + | |
| − | | + | |
| − | === Update & Save Your Patch ===
| + | |
| − | | + | |
| − | * In PuTTY, go to your patch directory (see [[#Create a Patch|this section if you've forgotten how to]]).
| + | |
| − | | + | |
| − | * Type this if this patch adds or delete files:
| + | |
| − | <source lang="bash">hg addremove</source>
| + | |
| − | | + | |
| − | * Type this to update your patch file:
| + | |
| − | <source lang="bash">hg qrefresh</source>
| + | |
| − | | + | |
| − | * Go to your patch directory in WinSCP and save a copy of your patch on your computer (see [[#Set Up Your Dreamhack|this section if you've forgotten where the patch folder is]]).
| + | |
| − | | + | |
| − | * Go back to the default code by typing (PATCHNAME is full name with extension too):
| + | |
| − | <source lang="bash">hg qpop -a
| + | |
| − | hg qdelete PATCHNAME</source>
| + | |
| − | | + | |
| − | For more commands, see http://hgbook.red-bean.com/read/mercurial-queues-reference.html
| + | |
| − | | + | |
| − | {{Warn|text=Do not manually edit your patch. This may cause errors and your patch won't work. Edit your file again. Refresh your patch. Test again.}}
| + | |
| − | | + | |
| − | | + | |
| − | == Put Your Patch On Bugzilla ==
| + | |
| − | | + | |
| − | * Log in onto [http://bugs.dwscoalition.org/ Bugzilla] and open your bug.
| + | |
| − | | + | |
| − | * Click on 'Add an Attachment' to attach your patch. Add a description and check 'patch'. Set Flags/Commit and Flags/Review to ? then click on Commit.
| + | |
| − | | + | |
| − | : If your patch depends on another patch being reviewed and committed first (you imported this other patch to make yours) then enter its number in the Depends On field and add your patch number in the Blocks field of the other patch. This will let committers know in which order these should be committed.
| + | |
| − | | + | |
| − | * Wait for someone to review and commit your patch. :) You're done. Congrats!
| + | |
| − | | + | |
| − | | + | |
| − | = Tips and Tricks =
| + | |
| − | | + | |
| − | * If your repositories won't update properly with <code>dwu</code>, you may need to go to dw-free/dw-nonfree and remove all your local changes with <code>hg update -C</code> then run <code>dwu</code> again.
| + | |
| − | | + | |
| − | * If your live code won't sync with your repository code, it may be because the files you've edited got saved using your computer time and not distant time. As the system relies on timestamps to see which files need to be updated, updates won't happen if live files seem to be more recent than repo files. Quickest trick is to change your computer time, open and save your files again so they get a later timestamp, refresh your patch and sync again.
| + | |
| − | | + | |
| − | * If there's something wrong with your patch queue (it says the patch is not in the series or you can't delete a patch) don't forget that you can start over: delete the patches folder with WinSCP and recreate it again in PuTTY using <code>hg qinit -c</code>.
| + | |
| − | | + | |
| − | * If something's really wrong you can also [[Dreamhack_Troubleshooting#I_want_to_wipe_my_install_and_start_over|rebuild you Dreamhack and start over]].
| + | |
| − | | + | |
| − | * To see what's string of text is used in a page append <code>?uselang=debug</code> to the page URL.
| + | |
| − | | + | |
| − | * As <dwuser>denise</dwuser> explained [http://dw-dev-training.dreamwidth.org/13233.html 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 <code>?uselang=debug</code> to make sure it's using the right string. If it is then it may be that things haven't been updated yet.
| + | |
| − | | + | |
| − | [[Category:Development]]
| + | |
| − | [[Category:Styles]]
| + | |
| − | [[Category:Getting Started]] | + | |
