User:Taldin/The Blacksmith's Forge(WIP)


 * Notes for a redesigned Blacksmith page.  Not yet released; please do not edit.   Feel free to leave comments on the Talk page if you like though. :)

Aspiring Blacksmiths must set up the proverbial forge; while you can see the code on Github, there is no way to run code directly from the Github repository. There are a few different possible installations depending on your preferences and personal operating system. Choose one of the following "forge" types: At a basic level, you can just set up a forge and learn a small handful of commands without really knowing what they're doing. However, since some commands are requests to alter the public HabitRPG repository, you'll want to be a responsible Blacksmith and know at least which commands are dangerous.
 * Vagrant is a self-contained virtual machine setup that runs Habits on Ubuntu Linux.
 * Grunt + NodeJS + MongooseDB (also known as MongoDB) runs on Windows.
 * OS X: (copy from the Blacksmith page).

You will also need to know how to update your local copies; since you aren't the only one making changes to the central copy of the code, regular updates will keep your code in sync so there is less of a chance of a problem when you merge code in.

Start off by creating a Github account at http://www.github.com A 'fork' is not a utensil in this case; it's a separate copy of the files for you to work on that allows you to write to it without any pesky permissions. You will be doing all your development on your personal fork, and when you finish an update, you will be asking the owner of the origin HabitRPG files to take (referred to as a 'pull') your modified files into the main copy.
 * Navigate to the HabitRPG main repository. Click the Fork button in the upper right hand corner to create a private fork.
 * Navigate to the HabitRPG/habitrpg-shared repository, and fork that one as well.
 * If you are developing for mobile devices, fork a copy of HabitRPG/habitrpg-mobile.

On your display screen for Github are two lists:

Popular Repositories - These are your forked copies. You are responsible for maintaining your own copy of a fork, and there are two copies of your fork; your local copy and the online copy on the Github site.

Repositories Contributed To - This is the master copy of HabitRPG. When you do pull requests, you file them against the master copy.

Terms You'll Need to Know
While you are working with HabitRPG's code, instructions here and on other pages may use the following terms.

Stuff to explain: editing files in locations, github checkout, syncing and pull requests.
 * Pull; request the rest of the world takes your fix.
 * Push: get the latest from the rest of the world.
 * Sync: Syncs your local copy with the online copy of your fork.   Whenever your version of the code is not exactly the same as the HabitRPG global code, it is considered to be 'out of sync'.
 * grunt: A program that compiles your habitrpg-shared directory.
 * npm: A program that compiles and runs the habitpg (main) directory.
 * source control: A tech term for 'all of your code changes are tracked.'
 * branch: The snapshot of your current code on your local or forked repository. Github's source control uses a branch system, so all coding is done on a labeled branch.  The main branch is called 'develop'. Good coding practice includes making a separate branch for your changes.
 * checkout: While it sounds like you're checking a library book out, you actually aren't.   It's just a switch of your active branch.
 * commit: Saves your changed files to the active branch, in preparation to publish the changes to the global Github copy.

Key Commands
-
 * git [command] - Runs a command in the git source control language. Use this to manipulate the code installation.
 * npm [command] - Runs HabitRPG (or generates a bunch of errors.)
 * bower install -f [library] - Installs additional support files (referred to as library files) to your local install of HabitRPG.
 * grunt - Compiles a set of changes before npm can be run.
 * mongo - Runs the database utility for HabitRPG users.
 * vagrant - Runs the virtual box

For fixing bugs, generally the develop-debug cycle is as follows: -
 * 1) Search the repository for relevant strings until you find the place in the code that needs fixing.
 * 2) Branch your fork so that you're developing the fix on a separate branch.  If you do the changes without changing this, you'll make the changes on develop, which will cause headaches later.
 * 3) Fix the bug.  TEST thoroughly.
 * 4) Commit your changes.
 * 5) Run a pull request from your modified branch, and document the changes as best as you can.
 * 6) Wait for your patch to be picked up.   It may take some time; it may not be picked up at all.   (instructions needed to close a pull request)

Strongly advise that you make yourself a twice weekly "Check GitHub for Latest Update." Your local copies of HabitRPG ideally should read as "This Branch is even with HabitRPG/develop."

If it reads 'This branch is X commits behind', do this:

git fetch upstream

git rebase upstream/develop

click the Sync button or git push

If it reads 'This branch is Y commits ahead', that means that your fix has not been picked up and you developed in the main develop directory. Wait.

If it reads 'This branch is Y commits ahead and X commits behind', you have a sync problem, because it means your copy of HabitRPG has a commit that nobody else has yet. When you do a git rebase upstream/develop, it's going to rewind your changes to the last version, and then reapply your fixes, leading to a duplicate of your personal commit -- and now it'll read Y+1 commits.'

Fix it this way:

git fetch upstream

git merge upstream/develop (NOTE: Not a rebase)

press the sync button

git rebase to the ID right before the one that has your unpicked up change to get rid of the merge message

git push --force

--

Whenever you do a merge or rebase, and it gives you conflicts, that means that one or more files need to be 'fixed.'  You do the following things:

Find the files that are causing problems.

Edit each file in a text editor, searching for >>>>> HEAD  and <<<<<< id label sections. The part above the ==== is the head, and the part below is the changed section. Resolve by choosing one version or the other, or fold in the changes. (Good luck.)

Save, then git add

Finally, commit the changed files.

--

New outline: Windows pages separate?

1. Downloaded Vagrant. Looks like a virtual machine. Makes sense, since I need a server. Vagrant is one of two possible ways to get Habits up and running. Alys recommends Vagrant. Vagrant also requires VirtualBox.

Vagrant is installed in the directory C:/HashiCorp by default. VirtualBox installs in C:/Oracle/VirtualBox.

Vagrant may not work for all people. It's not working for me across two machines. Extra steps involve finding a missing bower_components directory, and the extra npm browserify and coffeeify commands below.

May also need: npm install karma-phantomjs-launcher

1a. Virtualbox needs a special command to go into longmode or something. This happens if you get the VT-x is disabled in the Bios: VBoxManage modifyvm --longmode off

2. Forked on Github. Needed to create a Github account. It looks like I have a private branch of Habits now. Okay, if that's the case, what did I need Vagrant for?

3. Found the 'clone on own desktop button. Now I downloaded Github for Windows. Looks like I need to add a repository from the dashboard. That's the + button on the upper left.

4. Looks like step 2 (git remote upstream setup) is no longer necessary on Windows at least.

5. Trying the local install route; there is no config.json.example file. Oh wait, never mind, this is the Unix instructions.

6. Windows instructions have me getting Mongodb. This makes sense.

MongoDB went somewhere, though, hopefully this tutorial will help. Mongo was installed to C:\Program Files\MongoDB 2.6 Standard. Do I need to run a Mongo windows service? Or just mongod?

7. Now I need Node.js. (http://nodejs.org/download/). Thats the 'npm' thing. It installed in C:\Program Files\nodejs.

8. Node allows you to use 'npm' commands, including the npm install -g grunt-cli command, which I guess installed grunt? i'm guessing I need npm install -g bower too...

9. I still need a config file  Okay, I ran 'npm init' and got a bunch of prompts for things I don't quite know what to fill in. Where did that local install of Habits go?

10.  OOOOH. I found the config.json.example file! It's in Github Habitrpg.

Roadblocking again with the bower.js file or something. Steps in the configuration thing don't work.

11. Promising - running inside the github shell may have made a difference. Lots of error messages though?

Nope. Not working.

-

Revised list of things:

Vagrant+Virtualbox OR GitShell+Grunt+Bower.

Both use Mongo and Node.js.

Need to modify the config.json.example in the downloaded fork from Github.

May need to create a directory if you see:

C:\Users\User\Documents\Source\Project>npm install

grunt missing bits (

>> Local Npm module "grunt-contrib-clean" not found. Is it installed?

>> Local Npm module "grunt-contrib-cssmin" not found. Is it installed?

>> Local Npm module "grunt-browserify" not found. Is it installed?

npm install grunt-contrib-clean grunt-contrib-cssmin grunt-browserify

npm install coffeeify in moment and lodash fixes the other bug...

-

For later use:

habitrpg-shared/locales/en/gear.json - flavor text for armor

habitrpg-shared/script/content.coffee - armor/item stats and stuff'

habitrpg-shared/dist/locales/en/questsContent.json - quest code

Workaround for the spritesmith bug is to recopy stuff in. Means you can't modify the sprites very well, possibly.

Broken symlink command? Instructions to fix are here.

http://superuser.com/questions/449400/access-is-denied-on-mklink

VERY IMPORTANT: You need to nuke the bower_components directory and relink to the node_modules section for anything to work!

@taldin :  "how do I recompile to see if the change took?" If it's in habitrpg-shared, cd to /vagrant/node_modules/habitrpg-shared and run . Under some circumstances (mostly image changes that you've made) you need to run   but normally you don't. Then kill the   process if it's still running in another window (control-C) and restart it with   (or type   while that process is running). Wait for the  output to say something with the word "Mongoose" in it, and then you can reload the localhost website. If it's not in habitrpg-shared, you can normally just reload the website (no need for anything else) but sometimes you might need to restart npm.

Note that this will only work if you've symlinked the habitrpg-shared directory to another location as described in the wiki docs. Tell me if you don't know where. It might be hidden.

https://help.github.com/articles/syncing-a-fork/ -- git fetch upstream, then git checkout develop, then git merge upstream/develop, and then sync on the Github for Windows screen. Which (no pun intended) syncs with what you said here, @moringa. (uneasy chuckle) What was supposed to be just a simple docs project is looking more like a 'ooooo shiny blacksmith...'

--

@taldin : Sorry, I forgot to reply to that. There are ways to undo commits but the best in this case is probably to abandon the branch that they're in, start a new one, and apply just the commits that you want. So  to create "newbranch" and make it identical to the latest official "develop". Then   where those codes are the IDs of the commits you want (specify as many of them as you like, or just one at time if you prefer). You can find the codes by going to the old branch and doing   (or look in github). The codes you see will be a lot longer than ones I've used (c53e6a23cf38f103bb9d89c52762ad15944c8286) but that's okay.

-2 days ago+1

to fix messy repeating cyclic commits on your github shared repository:

Find the last place before your commits took place.

Right click the link to get the ID.

git reset -- hard 

git push --force (nukes the bad changes)

git fetch upstream (gets a fresh copy locally)

git rebase upstream/develop (copies local update to local)

git push (push local update to remote)

---

To get the updates, working around changes on develop that haven't been picked up yet:

git fetch upstream

git merge upstream/develop (NOTE: Not a rebase)

press the sync button

git rebase to the ID right before the one that has your unpicked up change to get rid of the merge message

git push --force