Difference between revisions of "Newbie Guide for Windows People Working on Minor Bugs"

From Dreamwidth Notes
Redirect page
Jump to: navigation, search
(+ link to status page on GH)
 
(28 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Warn|text=This guide is currently being rewritten to reflect the new workflow. Some things may be unclear or erroneous and some things may be missing. Please be patient.}}
+
#REDIRECT [[Newbie_Guide:_Getting_Started_on_Windows]]
 
+
{{Note|text=Feel free to correct, expand, do anything which could make this better and clearer. ^_^}}
+
 
+
 
+
= 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?
+
 
+
# You need a Github account to be able to fetch the Dreamwith code, create your own copies of it, and upload your own changes. This is both where all the Dreamwidth code comes from and where your own code will end on but it's only a gateway: you can't do much on github.com itself.
+
# 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 get to play with and modify.
+
# You need PuTTY to connect GitHub to your Dreamhack, to connect your Dreamhack to GitHub, and access and manage everything. In short, PuTTY is your true command center.
+
# You need WinSCP to visualize your Dreamhack files and be able to open them in a text editor. It's pretty much like Explorer for your Dreamhack.
+
# You need a text editor to edit your files.
+
# You need a Bugzilla account to find bugs, files bugs and upload patches.
+
 
+
== Create an account on GitHub ==
+
 
+
Go to [http://www.github.com/ GitHub], click on 'sign up and pricing' and create a free account. I suggest you pick a username people are familiar with and the same username you'll have on your Bugzilla account.
+
 
+
 
+
== Get a Dreamhack ==
+
 
+
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'. Your username is used to manage your Dreamhack and to create the URL where your Dreamhack will be located at so you can pick anything. Your email address is used to send you a welcome e-mail which contains important information as well as various alerts. You can pick any of your existing email addresses or choose to create an email account entirely devoted to your development work.
+
 
+
Once you're done, you should get an e-mail with your login username and a password. Don't lose it.
+
 
+
 
+
== Install PuTTY ==
+
 
+
* Download 'Windows installer for everything except PuTTYtel' .exe file at [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html 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 e-mail when asked. Note that no characters are displayed and the cursor won't move. It's normal.
+
 
+
* Change your password by typing:
+
<syntaxhighlight lang="bash">passwd</syntaxhighlight>
+
 
+
* Your default Dreamhack account is called system. Type this to set its password:
+
 
+
<syntaxhighlight lang="bash">$LJHOME/bin/upgrading/make_system.pl</syntaxhighlight>
+
 
+
 
+
== Install WinSCP ==
+
 
+
* 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 rarely need to access my computer files but choose what's easiest for you.
+
 
+
* Use "hack.dreamwidth.net" for the host name. Enter your username and the password you typed when you did <code>passwd</code> on PuTTY. Click on Save then on Login.
+
 
+
 
+
== Get a good text editor ==
+
 
+
While you can use Notepad, I recommend [http://notepad-plus-plus.org/download/ Notepad++] instead. It's free, simple and will make editing much easier.
+
 
+
 
+
== Create a Bugzilla account ==
+
 
+
Simply [http://bugs.dwscoalition.org/createaccount.cgi click here].
+
 
+
: N.B. 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 name, a nickname, your username again, etc. You don't have to give your real name if you don't want to.
+
 
+
 
+
= Set things up =
+
 
+
== 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 we know the two are connected.
+
 
+
Dreamwidth is divided into two parts: a 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 (the logo for example) 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.
+
 
+
 
+
== On your Dreamhack ==
+
 
+
Now you need to 'import' both of these onto your Dreamhack and link them to the original Dreamwidth repositories on GitHub so you can easily fetch updates.
+
 
+
To do so, [[Moving_your_Dreamwidth_installation_to_use_Github#Stop_the_server_and_all_workers | follow all the steps from this point on until you start your server again]] (but skip the 'non-dreamhack users' section, of course).
+
 
+
 
+
== Further configuration steps ==
+
 
+
These are not mandatory but will make your life easier.
+
 
+
 
+
=== Change some git settings ===
+
 
+
On PuTTY, I suggest going through [[Git_settings#Recommended_settings|all the steps mentioned in this section]].
+
 
+
{{Warn|text=If anybody knows how to make your default Windows editor git's default editor, please say so. I've read multiple articles on this topic and nothing worked for me.}}
+
 
+
 
+
=== Give special abilities to your system account ===
+
 
+
* Log in to your Dreamhack (http://www.USERNAME.hack.dreamwidth.net/) using system and your password.
+
 
+
* Go to [http://www.USERNAME.hack.dreamwidth.net/admin/priv/ 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 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 <code>/dw/ext/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.
+
 
+
* In PuTTY, type this to make the changes go live on your Dreamhack:
+
 
+
<syntaxhighlight lang="bash">$LJHOME/bin/upgrading/update-db.pl -r -p --innodb
+
$LJHOME/bin/upgrading/update-db.pl -r --cluster=all --innodb
+
$LJHOME/bin/upgrading/texttool.pl load</syntaxhighlight>
+
 
+
 
+
=== Customize PuTTY and Notepad++ ===
+
 
+
See these articles for details: [[PuTTY]], [[Editor:_Notepad_plus_plus | Notepad++]].
+
 
+
 
+
= Make sure things are up-to-date =
+
 
+
Important: you can generally get explanations about any bash command using <code>help COMMAND</code> (e.g. <code>help cd</code>) and any git command using <code>git COMMAND -h</code> (e.g <code>git pull -h</code>).
+
 
+
 
+
== Update your code ==
+
 
+
Code is committed by developers all the time. You must always update your repositories before you do anything else.
+
 
+
*  Use the <code>pull</code> command to fetch updates to each of the base branch:
+
 
+
<syntaxhighlight lang="bash">cd $LJHOME
+
git pull dreamwidth develop:develop
+
git pull dreamwidth master:master</syntaxhighlight>
+
 
+
* Then use the <code>push</code> command to forward the changes on your GitHub fork:
+
 
+
<syntaxhighlight lang="bash">git push origin develop
+
git push origin master</syntaxhighlight>
+
 
+
: N.B. When you do this you be will asked for your password on GitHub. Again, the cursor won't move as you type it. This is normal.
+
 
+
* For the nonfree part of the code, the commands are exactly the same except the first one, as nonfree is in a different folder:
+
 
+
<syntaxhighlight lang="bash">cd $LJHOME/ext/dw-nonfree</syntaxhighlight>
+
 
+
* You can also create a script to make this process simpler: see [[Dev_Maintenance#dwu_-_Updating_the_repos | this article]].
+
 
+
: N.B. To create a new file on WinSCP, right click into the correct folder (<code>/bin</code> here) then click on New/File.
+
 
+
 
+
== Update your database ==
+
 
+
* We're already seen this once but here it is again:
+
 
+
<syntaxhighlight lang="bash">$LJHOME/bin/upgrading/update-db.pl -r -p --innodb
+
$LJHOME/bin/upgrading/update-db.pl -r --cluster=all --innodb
+
$LJHOME/bin/upgrading/texttool.pl load</syntaxhighlight>
+
 
+
* You can also create a script to make this process simpler: see [[Dev_Maintenance#dwdb_-_Updating_the_database | this article]].
+
 
+
 
+
= Make changes to your local code =
+
 
+
== 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.
+
 
+
* To assign a bug to yourself, enter your Bugzilla e-mail address in Assign To and set the status to IN_PROGRESS.
+
 
+
: To make this easier, you can also use one of <dwuser>fu</dwuser>'s Greasemonkey scripts: [http://www.afunamatata.com/greasemonkey/ Dreamwidth Bug Grabber]. Click on (grab!) next to Assign To and this will edit it and Status for you. Click on Save Changes of course.
+
 
+
 
+
== Create a local branch stemming from develop ==
+
 
+
* Remember that your repository has two branches: master and develop. You always want to work in develop so make sure you're there first using the <code>checkout</code> command:
+
 
+
<syntaxhighlight lang="bash">git checkout develop</syntaxhighlight>
+
 
+
* Now you can create a new branch specifically dedicated to the bug you want to work on using the <code>branch</code> command. It's best if you use the bug number and a short description as your branch name:
+
 
+
<syntaxhighlight lang="bash">git branch BRANCHNAME</syntaxhighlight>
+
 
+
: It is best if you use the bug number and a short description as your branch name: <code>bug####/short_description</code>
+
 
+
* To switch to this branch, use the <code>checkout</code> command again:
+
 
+
<syntaxhighlight lang="bash">git checkout BRANCHNAME</syntaxhighlight>
+
 
+
* You can also create and switch to a branch at the same time using:
+
 
+
<syntaxhighlight lang="bash">git checkout -b BRANCHNAME</syntaxhighlight>
+
 
+
* And that's it. Now you can start coding!
+
 
+
 
+
== Work, work, work ==
+
 
+
* Use WinSCP to open the file you need to edit, add new files or delete existing ones.
+
 
+
* Remember that the free part of the code is in <code>~/dw/*</code> while the non-free part is in <code>~/dw/ext/dw-nonfree/*</code>.
+
 
+
* If you're working on site pages, you're working on .bml files. These are in <code>~dw/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/cgi-bin/DW/</code> or <code>~dw/LJ/</code>.
+
 
+
* For text strings which are not in <code>~dw/htdocs/xxx.bml.text</code> files, see <code>~dw/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:
+
 
+
<syntaxhighlight lang="bash">grep -ri "find this text" * | more</syntaxhighlight>
+
 
+
: This will search for "find this text" in all files and display it page by page.
+
 
+
<syntaxhighlight lang="bash">grep -ril "find this text" * | more</syntaxhighlight>
+
 
+
: This will search for "find this text" in all files but only display the relevant filenames and not any excerpts.
+
 
+
<syntaxhighlight lang="bash">grep -rl print_entry $LJHOME/bin/upgrading/s2layers</syntaxhighlight>
+
 
+
: This will search for files containing "print_entry" in the /s2layers folder, and only display the filenames as results.
+
 
+
 
+
== Test your changes on your Dreamhack ==
+
 
+
* In PuTTY, stop your Dreamhack:
+
<syntaxhighlight lang="bash">stop-apache</syntaxhighlight>
+
 
+
* Update your database by typing this or <code>dwdb</code>:
+
 
+
<syntaxhighlight lang="bash">$LJHOME/bin/upgrading/update-db.pl -r -p --innodb
+
$LJHOME/bin/upgrading/update-db.pl -r --cluster=all --innodb
+
$LJHOME/bin/upgrading/texttool.pl load</syntaxhighlight>
+
 
+
* Start your Dreamhack again:
+
<syntaxhighlight lang="bash">start-apache</syntaxhighlight>
+
 
+
* 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.
+
 
+
 
+
== Mark your local changes as ready to be committed ==
+
 
+
Before being committed, work is moved to a staging area. Think of it as the "Ready? Steady" before the "Go!". At this point nothing is definitive and you can easily change things.
+
 
+
* First, make sure you've made every change you wanted to make by using the <code>status</code> command:
+
 
+
<syntaxhighlight lang="bash">git status</syntaxhighlight>
+
 
+
* If things look good you can add your changes to the staging ('pre-commit') area using the <code>add</code> command:
+
 
+
<syntaxhighlight lang="bash">git add FILENAME</syntaxhighlight>
+
 
+
* To add all files which have been updated at once you can use:
+
 
+
FIXME: really? need to do a little testing with deleted files
+
 
+
<syntaxhighlight lang="bash">git add -u</syntaxhighlight>
+
 
+
* To add all files which have been added or updated at once use this instead:
+
 
+
<syntaxhighlight lang="bash">git add .</syntaxhighlight>
+
 
+
* If you realize you need to do some more work it's ok. Edit files again and use <code>add</code> again when you're done.
+
 
+
FIXME: what if I want to reset everything?
+
 
+
 
+
== Commit your changes locally ==
+
 
+
* If you think you're done with your work at this point you can commit your changes locally using the <code>commit</code> command:
+
 
+
<syntaxhighlight lang="bash">git commit -m "commit message"</syntaxhighlight>
+
 
+
: In the commit message explain briefly what this commit does.
+
 
+
* If you realize later you need to do some more work it's ok too. You can update your commit using <code>--amend</code>:
+
 
+
<syntaxhighlight lang="bash">git commit --amend -m "new commit message"</syntaxhighlight>
+
 
+
: N.B. You can also use this to change the commit message.
+
 
+
 
+
= Go from local to the World Wide Web =
+
 
+
== Push the changes to your github.com repository ==
+
 
+
You should only push your local changes to your develop branch on github.com once you've finished your work and won't go back to it again as it's harder to change things from this point on.
+
 
+
If you're sure use the <code>push</code> command and the branch name:
+
 
+
<syntaxhighlight lang="bash">git push origin BRANCHNAME</syntaxhighlight>
+
 
+
 
+
== Request your changes to be pulled into the main code ==
+
 
+
On your GitHub page, click on the correct repository (dw-free or dw-nonfree), select the correct branch in the branch drop-down menu (below 'Clone in Windows') then click on Pull Request below.
+
 
+
In the pull request message, mention the bug number and bug title again, provide a link to the bug on Bugzilla, and explain what your patch does.
+
 
+
: N.B. If there's a delay between the moment you pushed your branch and the moment it appears on GitHub, [https://status.github.com/ check its status page], wait and refresh. :)
+
 
+
 
+
== Mention the pull request on Bugzilla ==
+
 
+
FIXME: is this necessary?
+
 
+
* Comment on the bug with a link to your pull request.
+
 
+
* Wait for someone to review and commit your patch. You're done. :)
+
 
+
 
+
= More: checking things =
+
 
+
* To check which branch you're on:
+
 
+
<syntaxhighlight lang="bash">git branch</syntaxhighlight>
+
 
+
: N.B. The branch you're on is noted with an asterisk.
+
 
+
* To see the changes you've made on the branch you're on before you stage them for commit or between commits:
+
 
+
<syntaxhighlight lang="bash">git diff</syntaxhighlight>
+
 
+
* To see all the changes you've made on the branch you're on before you commit them:
+
 
+
<syntaxhighlight lang="bash">git status -v</syntaxhighlight>
+
 
+
* To see which files you've added, removed, modified on the branch you're on before you commit them and whether they're stage for commit:
+
 
+
<syntaxhighlight lang="bash">git status -s</syntaxhighlight>
+
 
+
 
+
= More: stashing your changes =
+
 
+
If you have work you haven't committed yet and you want to work on another bug or update your master and develop branches you need to stash your work first. It's generally good practice to do this every time you have work you haven't committed.
+
 
+
* Make sure you're on the right branch using the <code>checkout</code> command.
+
 
+
* You can put away your work using the <code>stash</code> command:
+
 
+
<syntaxhighlight lang="bash">git stash</syntaxhighlight>
+
 
+
* And bring it back with:
+
 
+
<syntaxhighlight lang="bash">git stash pop</syntaxhighlight>
+
 
+
 
+
= More: working in stages =
+
 
+
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.
+
 
+
To go back to a previous commit use the <code>reset</code> command:
+
 
+
FIXME: code missing
+
 
+
 
+
= More: renaming and deleting branches =
+
 
+
* To delete a branch locally:
+
 
+
<syntaxhighlight lang="bash">git branch -d BRANCHNAME</syntaxhighlight>
+
 
+
* To rename a branch locally:
+
 
+
<syntaxhighlight lang="bash">git branch -m OLDNAME NEWNAME</syntaxhighlight>
+
 
+
: N.B. This will work even if you've committed and pushed some changes already. However, if you have, it will not rename the branch on your GitHub fork but create a new identical one. You will need to delete the branch on GitHub.
+
 
+
* To delete a branch on your GitHub fork:
+
 
+
<syntaxhighlight lang="bash">git push origin --delete BRANCHNAME</syntaxhighlight>
+
 
+
 
+
= More: troubleshooting tips =
+
 
+
== Issues with text strings ==
+
 
+
* 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 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 <dwcomm>dw_maintenance</dwcomm>.
+
 
+
== Starting over ==
+
 
+
* 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]].
+
 
+
* Delete your copies of the Dreamwidth repositories:
+
 
+
FIXME: write
+
 
+
 
+
= References =
+
 
+
* [[Moving_your_Dreamwidth_installation_to_use_Github|Moving to GitHub]]
+
* [[Dev_Maintenance|Development Maintenance]]
+
* [[Draft:_Github_development_process|Github Development Process]]
+
* [http://ss64.com/bash/ Bash commands]
+
* [[Git_Getting_Started|Git: Getting Started]]
+
* [http://rogerdudler.github.com/git-guide/index.html Git - The Simple Guide]
+
* [http://gitref.org/index.html Git Reference]
+
* [http://learn.github.com/p/intro.html Learn.GitHub]
+
* [http://git-scm.com/documentation Git Documentation]
+
 
+
[[Category:Development]]
+
[[Category:Getting Started]]
+

Latest revision as of 16:20, 13 March 2013