Difference between revisions of "Newbie Guide: Getting Started on Windows"
m |
m (Updating SSH hostname for Dreamhacks.) |
||
(20 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
{{Note|text=Feel free to correct, expand, do anything which could make this better and clearer. ^_^}} | {{Note|text=Feel free to correct, expand, do anything which could make this better and clearer. ^_^}} | ||
− | {{Note|text=If you have a different OS you may find this | + | {{Note|text=If you have a different OS you may still find this helpful. While you may not need to install and set up any software the rest is pretty much universal.}} |
= Contributor Licensing Agreement = | = Contributor Licensing Agreement = | ||
− | The very first thing you need to do is [[Contributor_Licensing_Agreement|read and sign | + | The very first thing you need to do is [[Contributor_Licensing_Agreement|read and sign a Contributor Licensing Agreement]] 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 used. 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. |
Line 14: | Line 14: | ||
So what do you need? | So what do you need? | ||
− | # You need a github.com account to be able to fetch the Dreamwith code, | + | # You need a github.com account to be able to fetch and copy the Dreamwith code, find issues to work on, and publish your code so it can be integrated to Dreamwidth. This is both where all the Dreamwidth code comes from and where your own code will end up but you won't do much work on the site 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 can | + | # 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 do whatever you want with. |
# 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. | # 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. | ||
# 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. | # 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. | ||
# You need a text editor to edit your files. | # You need a text editor to edit your files. | ||
− | |||
− | |||
− | |||
== Create an account on GitHub == | == Create an account on GitHub == | ||
− | Go to [ | + | Go to [https://github.com/ GitHub] and create your account. |
Line 32: | Line 29: | ||
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. | 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 | + | 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 can't 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 free part go to https://github.com/dreamwidth/dw-free and click on Fork on the upper right corner. | ||
Line 41: | Line 38: | ||
== Get a Dreamhack == | == Get a Dreamhack == | ||
− | Apply for a Dreamhack by [http://hack.dreamwidth.net/apply.shtml filling this form]. | + | Apply for a Dreamhack by [http://hack.dreamwidth.net/apply.shtml filling this form]. You can pick anything as your username. The email address you choose is used to send you important info and alerts. |
− | : N.B. Some users like having a separate | + | : N.B. Some users like having a separate address 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. | Once you're done, you should get an email with your login username and a password. Don't lose it. | ||
Line 49: | Line 46: | ||
== Install PuTTY == | == Install PuTTY == | ||
− | * Download | + | * Download it at [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html] 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. | + | * Run PuTTY. In the configuration window, enter "ssh-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. | * Click on Open. If you get a pop-up message about a key, click Yes. | ||
Line 67: | Line 64: | ||
== Install WinSCP == | == Install WinSCP == | ||
− | * Install [http://winscp.net/eng/download.php | + | * Install it at [http://winscp.net/eng/download.php]. 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 works like Windows Explorer and only displays your Dreamhack files. 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 <code>passwd</code> on PuTTY. Click on Save then on Login. | + | * Use "ssh-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. |
Line 75: | Line 72: | ||
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. | 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. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
Line 122: | Line 112: | ||
Code is committed by developers all the time. You must always update your repositories before you do anything else. | Code is committed by developers all the time. You must always update your repositories before you do anything else. | ||
− | * Go to [[Dev_Maintenance#dwu_-_Updating_the_repos | this article]] and | + | * Go to [[Dev_Maintenance#dwu_-_Updating_the_repos | this article]] and follow the instructions given there. |
− | + | * Make sure to check for updates as the script occasionally changes. | |
− | + | ||
− | * Make sure to check for updates | + | |
: N.B. To create a new file open WinSCP, right click into the correct folder (<code>/bin</code> here) then click on New/File. | : N.B. To create a new file open WinSCP, right click into the correct folder (<code>/bin</code> here) then click on New/File. | ||
− | = Make changes to your | + | = Make changes to your Dreamhack = |
− | == Find | + | == Find and claim issues == |
− | <strong>--> | + | <strong>--> on github.com</strong> |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
+ | Issues are listed at https://github.com/dreamwidth/dw-free/issues and https://github.com/dreamwidth/dw-nonfree/issues. You can use the search bar at the top to browse labels. | ||
+ | Once you've found something you like comment on the issue to 'claim' it. | ||
− | == Create a | + | == Create a branch stemming from develop == |
Important: in PuTTY, you can get explanations about bash commands using <code>help COMMAND</code> (e.g. <code>help cd</code>) and any git commands using <code>git COMMAND -h</code> (e.g <code>git pull -h</code>). | Important: in PuTTY, you can get explanations about bash commands using <code>help COMMAND</code> (e.g. <code>help cd</code>) and any git commands using <code>git COMMAND -h</code> (e.g <code>git pull -h</code>). | ||
Line 160: | Line 142: | ||
<syntaxhighlight lang="bash">git checkout develop</syntaxhighlight> | <syntaxhighlight lang="bash">git checkout develop</syntaxhighlight> | ||
− | * Now you can create a new branch specifically dedicated to the | + | * Now you can create a new branch specifically dedicated to the issue you want to work on: |
<syntaxhighlight lang="bash">git branch BRANCH_NAME</syntaxhighlight> | <syntaxhighlight lang="bash">git branch BRANCH_NAME</syntaxhighlight> | ||
− | : N.B. | + | : N.B. Use the issue number and a short description as your branch name: <code>bug #xxx/short-description</code> |
− | * | + | * Switch to your new branch: |
<syntaxhighlight lang="bash">git checkout BRANCH_NAME</syntaxhighlight> | <syntaxhighlight lang="bash">git checkout BRANCH_NAME</syntaxhighlight> | ||
* And that's it. Now you can start coding! | * And that's it. Now you can start coding! | ||
− | |||
== Work, work, work == | == Work, work, work == | ||
− | <strong>--> in WinSCP and your editor</strong> | + | <strong>--> in WinSCP and your text editor</strong> |
* In WinSCP right click to edit the file you want to work on. | * In WinSCP right click to edit the file you want to work on. | ||
Line 181: | Line 162: | ||
* 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>. | * 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>. | ||
− | * Site pages are either [[BML|.bml]] or [[TT|.tt]] files. You can find them in <code>~dw/htdocs/</code> and <code>~dw/views/</code>. They may use .pm modules | + | * Site pages are either [[BML|.bml]] or [[TT|.tt]] files. You can find them in <code>~dw/htdocs/</code> and <code>~dw/views/</code>. They may use .pm modules and widgets, found in <code>~dw/cgi-bin/LJ/</code> and <code>~dw/cgi-bin/DW/</code>. |
− | * Text strings | + | * Text strings are in <code>~dw/htdocs/xxx.bml.text</code>, <code>~dw/views/xxx.tt.text</code>) or <code>~dw/bin/upgrading/en.dat</code>. |
* For more specific searches, see [[Dev_Finding_Things|this article]] on how to use <code>rgrep</code> and <code>find</code>. | * For more specific searches, see [[Dev_Finding_Things|this article]] on how to use <code>rgrep</code> and <code>find</code>. | ||
Line 194: | Line 175: | ||
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. | 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, your changes won't go live on | + | : N.B. In some rare instances, your changes won't go live instantly on your hack and you may need to [[Dev_Maintenance#Update_your_database|update your database first]]. |
− | == Mark your | + | == Mark your changes as ready to be committed == |
<strong>--> in PuTTY</strong> | <strong>--> in PuTTY</strong> | ||
Line 203: | Line 184: | ||
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. | 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. | ||
− | * | + | * To add the changes you've made on a specific file: |
<syntaxhighlight lang="bash">git add FILE_NAME</syntaxhighlight> | <syntaxhighlight lang="bash">git add FILE_NAME</syntaxhighlight> | ||
− | * To add all files which have been | + | * To add all files which have been edited or deleted at once: |
<syntaxhighlight lang="bash">git add -u</syntaxhighlight> | <syntaxhighlight lang="bash">git add -u</syntaxhighlight> | ||
− | * To add all files which have been added, deleted or | + | * To add all files which have been added, deleted or edited at once: |
<syntaxhighlight lang="bash">git add .</syntaxhighlight> | <syntaxhighlight lang="bash">git add .</syntaxhighlight> | ||
− | * If you realize you need to do some more work, edit files again and use <code>add</code> | + | * If you realize you need to do some more work, edit the files again and use <code>add</code> when you're done. It's that simple. |
− | == Commit your changes | + | == Commit your changes == |
<strong>--> in PuTTY</strong> | <strong>--> in PuTTY</strong> | ||
− | * If you think you're done with your work at this point you can commit your changes | + | * If you think you're done with your work at this point you can commit your changes: |
<syntaxhighlight lang="bash">git commit</syntaxhighlight> | <syntaxhighlight lang="bash">git commit</syntaxhighlight> | ||
Line 228: | Line 209: | ||
* 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). | * 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 | + | * Here's an example of commit message: |
− | <code> | + | <code>Bug #123. Short subject |
+ | |||
+ | Fixes #123. | ||
Patch description | Patch description | ||
Line 236: | Line 219: | ||
Description can go on several short lines.</code> | Description can go on several short lines.</code> | ||
− | * Hit Ctrl+X, 'y' then | + | * 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: | * If you you need to do some more work later you can update your commit: | ||
Line 246: | Line 229: | ||
* 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. | * 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. | ||
+ | = Publish your code = | ||
− | + | == Push your code to your github.com repository == | |
− | + | ||
− | == Push | + | |
<strong>--> in PuTTY</strong> | <strong>--> in PuTTY</strong> | ||
− | You should only push your | + | You should only push your 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 <code>push</code> command and the branch name: |
<syntaxhighlight lang="bash">git push origin BRANCH_NAME</syntaxhighlight> | <syntaxhighlight lang="bash">git push origin BRANCH_NAME</syntaxhighlight> | ||
− | == Request your | + | == Request your code to be pulled into the original Dreamwidth repository == |
<strong>--> on github.com</strong> | <strong>--> on github.com</strong> | ||
− | 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 | + | 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 then on Compare and Pull Request. Once you've checked things over, click on Send Pull Request on the right side. |
+ | Finally, comment on the pull request to say it 'fixes #xxx' where #xxx is the issue number. | ||
: N.B. If there's an unusual delay between the moment you pushed your branch and the moment it appears on GitHub, [https://status.github.com/ check the status page]. | : N.B. If there's an unusual delay between the moment you pushed your branch and the moment it appears on GitHub, [https://status.github.com/ check the status page]. | ||
Line 269: | Line 252: | ||
== What now? == | == What now? == | ||
− | <strong>--> | + | <strong>--> on github.com</strong> |
− | * You'll get | + | * You'll get a notification once your pull request has been merged into the original develop branch, and the issue will be closed if no more work is needed. |
− | + | * On your profile your request will be marked as merged. | |
− | + | ||
− | * On | + | |
* That's it! You're done. Congratulations! | * That's it! You're done. Congratulations! | ||
− | + | = Help! = | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | = Help! | + | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | If something's | + | If something's wrong you can always ask for help at <dwcomm>dw_dev_training</dwcomm> or on the #dreamwidth-dev [[:Category:IRC|IRC]] channel. |
− | = | + | = Reading / References = |
− | To understand things better, I suggest reading relevant sections of [http://rogerdudler.github.com/git-guide/index.html Git - The Simple Guide], watching part of <em>Git for Ages 4 and Up</em> ([http://www.youtube.com/watch?v=1ffBJ4sVUb4 Watch on YouTube] or [http://mirror.internode.on.net/pub/linux.conf.au/2013/mp4/Git_For_Ages_4_And_Up.mp4 Download]), and reading the first three chapters of [http://git-scm.com/book Pro Git]. | + | To understand things better, I suggest reading [http://guides.github.com/overviews/flow/ the GitHub Workflow guide from github.com], relevant sections of [http://rogerdudler.github.com/git-guide/index.html Git - The Simple Guide], watching part of <em>Git for Ages 4 and Up</em> ([http://www.youtube.com/watch?v=1ffBJ4sVUb4 Watch on YouTube] or [http://mirror.internode.on.net/pub/linux.conf.au/2013/mp4/Git_For_Ages_4_And_Up.mp4 Download]), and reading the first three chapters of [http://git-scm.com/book Pro Git]. |
− | For lots of useful commands, see [[How | + | For lots of useful commands, see [[Git How To]]. |
Other useful references: | Other useful references: | ||
Line 328: | Line 276: | ||
* [[Moving_your_Dreamwidth_installation_to_use_Github|Moving to GitHub]] | * [[Moving_your_Dreamwidth_installation_to_use_Github|Moving to GitHub]] | ||
* [[Dev_Maintenance|Development Maintenance]] | * [[Dev_Maintenance|Development Maintenance]] | ||
− | |||
* [http://ss64.com/bash/ Bash commands] | * [http://ss64.com/bash/ Bash commands] | ||
* [[Git_Getting_Started|Git: Getting Started]] | * [[Git_Getting_Started|Git: Getting Started]] | ||
Line 334: | Line 281: | ||
* [http://git-scm.com/book/commands Pro Git - Index of Commands] | * [http://git-scm.com/book/commands Pro Git - Index of Commands] | ||
* [http://git-scm.com/docs Git Reference] | * [http://git-scm.com/docs Git Reference] | ||
− | |||
[[Category:Dreamhack]] | [[Category:Dreamhack]] |
Latest revision as of 04:47, 4 April 2017
Contents
Contributor Licensing Agreement
The very first thing you need to do is read and sign a Contributor Licensing Agreement 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 used. 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?
- You need a github.com account to be able to fetch and copy the Dreamwith code, find issues to work on, and publish your code so it can be integrated to Dreamwidth. This is both where all the Dreamwidth code comes from and where your own code will end up but you won't do much work on the site 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 can do whatever you want with.
- 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.
- 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.
- You need a text editor to edit your files.
Create an account on GitHub
Go to GitHub and create your account.
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 can't 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. You can pick anything as your username. The email address you choose is used to send you important info and alerts.
- N.B. Some users like having a separate address 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 it at [1] and install it.
- Run PuTTY. In the configuration window, enter "ssh-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 it at [2]. 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 works like Windows Explorer and only displays your Dreamhack files. Either mode is fine. Pick what you're most used to.
- Use "ssh-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.
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 onconfig.pl
. Find$USE_ACCT_CODES = 1;
and change 1 to0
. 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 follow the instructions given there.
- Make sure to check for updates as the script occasionally changes.
- 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 Dreamhack
Find and claim issues
--> on github.com
Issues are listed at https://github.com/dreamwidth/dw-free/issues and https://github.com/dreamwidth/dw-nonfree/issues. You can use the search bar at the top to browse labels. Once you've found something you like comment on the issue to 'claim' it.
Create a 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 typecd $LJHOME
. - if you want to work in dw-nonfree you need to be in
~/dw/ext/dw-nonfree$
. If you're not typecd $LJHOME/ext/dw-nonfree
- if you want to work in dw-free you need to be in
- 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 issue you want to work on:
git branch BRANCH_NAME
- N.B. Use the issue number and a short description as your branch name:
bug #xxx/short-description
- Switch to your new branch:
git checkout BRANCH_NAME
- And that's it. Now you can start coding!
Work, work, work
--> in WinSCP and your text 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 and widgets, found in~dw/cgi-bin/LJ/
and~dw/cgi-bin/DW/
.
- Text strings are in
~dw/htdocs/xxx.bml.text
,~dw/views/xxx.tt.text
) or~dw/bin/upgrading/en.dat
.
- For more specific searches, see this article on how to use
rgrep
andfind
.
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, your changes won't go live instantly on your hack and you may need to update your database first.
Mark your 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.
- To add the changes you've made on a specific file:
git add FILE_NAME
- To add all files which have been edited or deleted at once:
git add -u
- To add all files which have been added, deleted or edited at once:
git add .
- If you realize you need to do some more work, edit the files again and use
add
when you're done. It's that simple.
Commit your changes
--> in PuTTY
- If you think you're done with your work at this point you can commit your changes:
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:
Bug #123. Short subject
Fixes #123.
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.
Publish your code
Push your code to your github.com repository
--> in PuTTY
You should only push your 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 code 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 then on Compare and Pull Request. Once you've checked things over, click on Send Pull Request on the right side. Finally, comment on the pull request to say it 'fixes #xxx' where #xxx is the issue number.
- 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?
--> on github.com
- You'll get a notification once your pull request has been merged into the original develop branch, and the issue will be closed if no more work is needed.
- On your profile your request will be marked as merged.
- That's it! You're done. Congratulations!
Help!
If something's wrong you can always ask for help at dw_dev_training or on the #dreamwidth-dev IRC channel.
Reading / References
To understand things better, I suggest reading the GitHub Workflow guide from github.com, 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 Git How To.
Other useful references: