Wednesday, April 1, 2015

Do You Need Cucumber or even BDD?





Do You Need BDD or Cucumber?

This is a debate that has been ongoing for a while in the development world.   

The crux of the arguments out there are have been:

  • "BDD is a lot of overhead", meaning writing the tests slows us down
  • "You don't need BDD, it's a waste of time"
  • "Business people don't care about technical Parts of BDD or writing the tests" so "They never write them so BDD is pointless"
I'm sure you've read or heard those arguments time and time again, I know I have.

I do not claim to be a master in BDD however I'm getting to the point to where I'm doing it enough to where I'm able to draw the lines and see those arguments start to shrink more and more.

Proof

You want Proof you say! Well you got it.

For this blog post I'm focused on a recent conversation I had with a close friend who is seasoned at BDD and TDD.  I passed him this argument by Kevin Liddle because I'm truly interested in working more with BDD daily, and want different opinions out there period.

He disagrees with some arguments out there against BDD as well as Cucumber.  Because in his organization it has only been a great tool and helps their organization and has seen much success with Cucumber.js.  He is running several large development teams right now in his organization (all of which are doing BDD and disciplined TDD) and has been promoted to drive his process down to and lead rest of the organization because it's worked so well for the company overall.

He has found success with BDD and specifically Cucumber.js in his organization all the way from the non-technical business stakeholders all the way down to acceptance of BDD from his own developers across all the teams he manages.

His organization isn't some start-up, it's big.  And things have to work well.  They're driving the next wave in fact and leading their industry in terms of the awesomeness coming out and competitors are taking notice and actually using their APIs as a result!  What more testamony to design, BDD, and TDD can one get.  This is real tangible stuff at a large organization with a lot of devs.  And if anything could put DHH's baseless argument against TDD to rest, this would be a great example.

The following is a summary of our interesting conversation and sheds some light on one good sized organization and their dev teams who have seen huge value in Gherkin, Cucumber, and BDD.

Remember the ".js" after Cucumber because it's significant as you will read further below.


"BDD is a Waste of Time!"

First, this is nonsense.

If you haven't seen the value yet, then most likely one of these reasons:

a) Have you tried to or are you actually coding BDD yet? 

If you've only read about it then then why make uninformed biased conclusions if you've never experienced it yourself right?

b) You've done some BDD but did it in an organization which has made a mess of it.  

Well then of course you might view it that way

c) Maybe your organization isn't going about it in a lean or clean way:
  • Cutting out QA completely from the equation
  • Maybe you're tests themselves are written poorly such as including implementation details in the Gherkin which should not be there.  BDD is for high level functional requirements, not the how to implement them
  • You're still using older framework that make it hell to maintain those kinds of tests and running them are slow because of that framework

For me, BDD Makes Sense and is Valuable Without Question

I've been doing some Cucumber.js for my own personal projects lately and it just makes complete sense.  BDD tests are a perfect starting point from Agile Story to starting the actual related code for that story.   Watch this video from Corey Haines, he shows you nicely how to start a new project both from a Business Domain / Priority List perspective right down into starting your first BDD tests, and then implementing the code via TDD.

BDD tests guide you.  I honestly can't think of not doing them anymore after having done some in Cucumber.js.  Because they force you to think about the business requirement at the highest level first.  It's a better starting point than taking some garble that varies from Story to Story and assuming you're getting off to the right start with just diving into your TDD tests.  Everything is clear when based off Gherkin and verifiable.

BDD tests drive the lower-level implementation.  That is they determine the direction and scope of your TDD tests once you're ready to implement the real code.  BDD forces you to think about what scenarios you need to think about first, as lean as possible, and at a high level.  And then that reduces the scope of your unit tests making the correlation of TDD tests to BDD tests a tight nit family.

A Proven Process

First off if you are trying to BDD in your organization and you're expecting Stakeholders, PMs, or QA to write any amount of code is a ridiculous expectation that shouldn't be in your organization in the first place and you are going about BDD completely wrong.  And that goes for QA too!  They shouldn't be writing BDD...period.

Business Stakeholders could give a crap about code.  They care about getting requirements right and seeing those being built succesfully and with high quality form the development team.

My friend told me BDD has only helped.  In no way is it debated in his organization, because it's produced results.  Proof first-hand in a large organization.  Because they do it right.

Quotes from my friend from our discussion

"You have to keep things in perspective.  We're talking about it in the context of Cucumber.js with Node.js, not older Cucumber frameworks.  Cucumber.js and older Cucumber are not the same in terms of speed to code and run those tests.  So the speed argument doesn't apply to what we do here.


As for the argument that business people won't write Gherkin or that Gherkin is a waste of time isn't true for our case.  

That's because all our business people have agreed as a standard to write acceptance criteria in Gherkin format right into their Jira Stories and we don't ask them to do anything other than that, that's where it stops.  That's not difficult for them to do, and they like it!  We don't expect them to write any code.  In fact we don't even really have QA anymore, we've trimmed QA out of testing completely and have very few QA resources period.

Our Engineers then simply take and copy the scenarios that are in Gherkin format from those Jira stories that were written by the non-technical managers and PMs, and and write a BDD test for them and it's not a big deal to any of our developers.

And Since it's fast to write tests and setup Cucumber.js over Node.js, there's not a problem with it being slow to run or code at all...so this is not the same as using older Cucumber to do this and so it's not a problem for our business or devs and it works great for everyone here.

Our team has been doing it for a while and don't complain about it…they actually like doing it.   Where teams start bitching and stuff is a dirty little secret.  It's usually those teams who have QA staff.  And the QA staff is essentially doing half of their testing for them.  Once you remove the QA staff from the equation then it's different.  

You tell the engineers they're responsible for the quality…then all of a sudden that automation makes a lot more sense to those engineers.  So that's the piece you are not seeing in those arguments also…is that most of these engineers tend to have QA resources as part of your team and is why BDD is getting a bad rep.

We then run our versioned automated functional tests (Cucumber.js BDD test suites) every 30 minutes against all our environments all the way up to production on our apps all the time."

That's what Gherkin is For
Given I am a user
When I go to the main landing page
And I see that there are some events scheduled for Metallica
If you think about it, how many times are you in an iteration planning meeting and you're trying to write some of the acceptance criteria and your description and details around that varies greatly in who wrote it in terms of how it's written...it's usually a big mess with no structure.  In Story A someone wrote it in a nice clear concise manor.  Fine.  In Story B for the same product, same iteration wrote too much, or wrote it messy because they have a language barrier, or just don't give a damn or just are not very good at writing to begin with.  That happens, because we are all different, we're all human.

But when you have your business stakeholders write the criteria all in Gherkin right in your story it just make complete sense.  That's the whole value of Gherkin to begin with.  A template to write clear and concise functional requirements anyone can understand and think out in a consistent and very clear manor.  

So stop having different people use different templates (or no template! even worse) for writing the acceptance criteria in your user stories.  Just use Gherkin style.  It's just too easy and it makes too much sense not to.  Be consistent.  Be clear.


Developers Take Gherkin and Write The BDD Tests Themselves, not QA

Yes I said Developers...not QA, nobody else.

No this is not far fetched and no this doesn't slow down the team.

Your developers (not QA!) simply and literally copy that Gherkin typed by your business owners from the stories and when they start on implementing a story, first they they do is create the Cucumber.js BDD tests starting with the Gherkin themselves and don't even question or complain about doing so because it just works.  

You start with the Gherkin written in whatever Agile Software you're using to create Stories, have the business people write that gerkin as acceptance criteria in the stories, then have engineers take that Gherkin and write the BDD tests.  After you have your BDD tests written, they serve as a guide in the next step which is to start writing the TDD to implement the real code for those BDD scenarios.  It's very much a controlled, clean, and fast way to get things done.  It's a lean way of coding and getting shit done.  

There's no going to QA or having an expectation for anyone but the developers to start implementing the rest that's under that BDD.

Cutting QA Out, Are you Joking?  You Jerk!

This is not a new concept.

It's not theory or wishful thinking for some organizations.  It's actually really being done more and more across organizations today as they embrace more Pair Programming coupled with TDD and figure out how to make BDD work.

When BDD is working right and is working for non-technical owners, that's where things start to change.

It's because some organizations utilizing BDD have gotten to a certain point to where their BDD process is driving things and working for all involved and that when oupled with TDD and simple design, everyone starts to see a very low bug count and even rare corner cases aren't there much anymore on all apps being developed or new features added or changed.  So you end up literally not needing to have that extra layer of a QA department bogging you down.  It's straight up business owners to devs.  The Business owners know what needs to be done to meet a requirement for the business and it's getting done by the developers effectively.

Developers code the BDD for the Gherkin, and develop the code via TDD.  There's really not much more to do and really not much need for much if any QA after that when everything is aligning this well in an organization.

Obviously Can Also Use Other Frameworks

I'm not completely biased toward Cucumber although my wordage might indicate that in this post.

Note that there are other test frameworks such as Mocha.js where you can kinda do the BDD and TDD all in one roof.  Currently I'm trying to use Mocha.js for the TDD tests and Cucumber for the BDD on my projects.

But I'd still see some value in using Gherkin-like wording in Agile Story acceptance criteria.  And then implementing the code for that by devs.  You could use other frameworks outside Cucumber is my point.  It's just that by adding the Gherkin-like wording is still valuable, clear, and maintainable at the story level when written in your Agile Stories during iteration planning.

Conclusion

I think the most important points coming out of our conversation were the following:

1)  Just have your stakeholders or PMs write the Gherkin syntax in the Agile Stories as the Acceptance Criteria, no coding required

2) Devs should be picking up the Gherkin from those stories and writing the BDD tests themselves, not QA

3) It's been proven to be a very Lean way of producing code and satisfying business requirements

4) Cucumber.js and Node.js changes the ballgame on the old argument of Cucumber is slow or time consuming for devs

5) The teams who have QA doing the BDD tests are actually putting up a wall to getting the actual work done and tested

6) QA is being removed from the equation more and more entirely, because bugs are low when BDD and TDD work well and you have clean, testable, and maintainable code as a result of that and keeping things simple / minimal / lean


Be Careful


So be careful of the general arguments out there against BDD in terms of if you need it or not.  And in my particular conversation, revolving around Cucumber.

Things are changing in both the BDD framework scene these days, and how BDD is being done.

Arguments that have existed against BDD and against Cucumber in this case are becoming stale and no longer true in some organizations.

Saturday, February 21, 2015

Setting Up WebStorm for io.js



I use JetBrains WebStorm as the main IDE for coding JavaScript.  I'm using it currently for coding with io.js, which is the new port off Node.js and I'm using this IDE to work with other libraries like express.js, mocha.js, and so on.


Initially I was in the editor trying to setup my project for a website recode and was coding some express.js code to get a web server and page up and running and noticed that JSHint and JSLint had trouble recognizing io.js (Node) and express.js in terms of JSHint and JSLint intellisense.


I found out there's a fair amount of configuring in WebStorm preferences that you need to be aware of and set for io.js, adding libraries like express.js, and so on. 


This will give a good list of what to do in general to get everything set right and intellisense working right for node.js, io.js, and any extra libraries you're tacking on (such as express.js, etc.).


Here's What I Saw initially


Initially before I started to have to fiddle with WebStorm preferences, this was the state of everything.  I had created a new project and initial boilerplate files and some initial code in express.js.








Notice JSHint and JSLint's intellisense has no clue what this node and express.js code is.

Preferences | Language & Frameworks | Javascript | Libraries


Preferences | Language & Frameworks | Node.js and npm










Here's What To Do


Ensure that you have a root package.json File With Correct Dependencies Defined


In the command prompt (bash), cd to the root project folder then type npm init
This will take you through a wizard to quickly and easily create your initial package.json file
Now you should have a root package.json meaning it's sitting in the root project folder
(My root folder is Website)














Ensure Your App's JS file is Inside Your node_modules Folder


Make sure your app.js (mine is called dimecasts.js) file is inside your node_modules folder that sits in the root of your project's parent folder






Preferences | Languages & Frameworks | JavaScript | Code Quality Tools


Make sure JSLint and JSHint validation are enabled; those should always be enabled period in WebStorm no matter what you're working on.  The point here was also to make sure that intellisense for both these tools could recognize Node and Express.js syntax..which was not working originally since we had to change some config settings as we're about to do below for Node and express.


Preferences | Editor | Inspections | JavaScript | Code Quality Tools

Enable JSHint and JSLint here also






Preferences | Plugins
This should have already been enabled by default when you installed WebStorm but double check that Node is enabled



Preferences | Languages & Frameworks | Node.js and npm
Change the path for Node interpreter to iojs





Now go to https://iojs.org/dist/ and download the source tar.gz file for whatever version you have for io.js.  Mine was 1.3.0 when I installed io.js.

Download the file to a local folder; I copied mine to /usr/local/bin/..Click Then configure and browse to that file.  Mine was iojs-v1.3.0.tar.gz







Now it should be all set after clicking Configure:





Preferences | Languages & Frameworks | JavaScript | Libraries
Now you should see an entry for Node.js Core Modules for the source you just configured in the previous step. 
You may need to close and re-open Webstorm to see this or 
File | Invalidate Caches / Restart


One you are able to see it, enable it.


Preferences | Languages & Frameworks | JavaScript | Libraries
Double click on the Node.js Core Modules item you just enabled and it'll open an Edit Library window.

Set it to Project Visibility





Be sure to also check the box for "Node.js Globals".

Now we need to add express.js library in here so that intellisense picks up syntax for this library.
Cilck the Add button and attach a file.  




Browse to where your express.js file is under your project directory.  Mine was here:








File | Invalidate Caches / Restart


For the settings to start to be applied, you need to invalidate the cache and restart WebStorm.
Then once I opened up my express code, all was happy, and I'm getting Intellisense for node.






Thursday, February 19, 2015

TDD - Don't Worry About Code Coverage In The Beginning



I came across a Quora question today on TDD and amount of Test Coverage to aim for. 

Here was my response.  But before I dive into that, let me state that TDD is an ongoing continual process of learning.  There are critical things you just can't skip, or things you have to become aware of and over time learn how to "do it right" and there are indeed right and wrong ways to go about it.  It's always a continual learning process as well, even for seasoned TDDer's.


1) People new to TDD or misunderstand it may be missing of the point of TDD Altogether


It's not only about tests and test coverage percentage.  

Sure you get coverage and confidence but it's even more about how TDD guides you and helps you to see things in code that you would not be seeing if you were to test after new code.  What you should be focused on is learning how to TDD, and striving to create clean, simple, maintainable code before you even think about % of test coverage you've got.

Also, there are a lot of teams out there who default to the conclusion that TDD == Just Unit Testing.  As a result, they immediately then conclude why should we even do TDD? We just do tests after, same thing, same effect...and after all we're "doing what works for us" so skat...


The "do what works for us" is fine and I believe a team should do that, but it's often used as a cop-out and reason not to try or learn and adopt TDD or in some cases doing to TDD what people have done to Agile which is to skip the goals and principles thereof.  That a team thinks they are doing TDD but some on the team think it's ok to skip one or more of the 3 laws of TDD (e.g. we can just skip the refactoring step because we can do that later because someone is breathing down our neck to get this feature out).  

And that's where the misunderstandings and assumptions start.  "Oh we have code coverage and we don't even need TDD! ", the party has started.  Or "TDD is the same thing, it's just adding code coverage, so we just add all the tests after".

I'm sorry to tell you but you missed the point of TDD and you don't understand it quite yet.

Such as:
  • helps you to produce leaner code because it forces you to strive for simplicity and forces you to be more simplistic during the creation of tests and production code as well as the refactoring step which forces you to go back and make things even more simplistic (means you are not skipping the refactoring step as well)
  • keeps you much more close to your code at all times in that it keeps you more aware and critical of your code at a micro level when you practice TDD
  • It's about verifying if your tests are valuable during each step of the way because you're getting that feedback early and getting it right after you get your test to go green

The level of feedback and guidance when you code via TDD is way different in my experience.  You're much more critical of your code when you go very small steps with TDD and adhere to the 3 principals.  The 3 are a tight loop that works wonders...and you do not skip one or more of the 3.  Only until you do it, will you understand how powerful TDD is and how much it's really making you more efficient as well as your team once you get used to it and know how to do it right.

2) High Code Coverage Doesn't Automatically Translate to Value

Why?  What if your tests suck?  Just because you have code coverage doesn't mean your tests are good ones, or the right ones. 

In fact you could have wasted time adding all the tests after that were not valuable in the first place whereas you would have saved time if you had Test Driven your code in the first place and end up with more tests that are valuable.

Now TDD helps with that, it helps because along the way when you're doing test first and driving the code, your tests are more likely to be focused, smaller because you force yourself to stop once they go green, and find out immediately if they are valuable in that they give you feedback you can trust because you're also running those tests very often throughout the coding of a feature.  

But even with TDD you can add tests that are a waste, tests you can't trust, tests that are doing way too much or testing the wrong modules of a system that don't need to be tested, and the list goes on...it's a matter of practice and experience and making sure you run the test suite continually as you code more and more production code.  It's just that TDD helps you to have less of those useless tests because if you are following the 3 laws, and adding tests as you go,  in my experience it's likely you'll have less of those invaluable tests vs. valuable.  Value means you are getting immediate feedback you can trust and the feedback is based on micro

3) You have to be careful with Wonderful Metrics

Extending point #2, Metrics are wonderful tools to gauge what's going on but when being reviewed and gauged in the wrong hands, they can also push for the wrong goals in the beginning, miss the point,  or push for stuff that's not providing true value for the business.  

Example:  At a previous job, all the team cared about for the majority of the time was meeting numbers for Goals and Objectives, referring to the code coverage for the team as a whole.  And didn't want TDD...they  figured it's a waste of time because "oh we know what TDD is already".  And most on the team were completely happy with always promoting and tacking on tests after finishing new production code.  

There was no real push for the team to learn TDD so that the team could go through it's motions correctly and see its true value.    Some even bluntly refused to do / work hard at learning how to do any unit testing period regardless of trying to get a team to adopt TDD...so the overall base code coverage was minimal in the first place since half the team refused to unit test, the code coverage might have been 80% as only a couple on the team decided they were worth while, so really that goal in the end only covered 20% of the overall code being produce on the team...and we still didn't know what % of the code truly gave us value.  We knew that tests were helping but we did not now what code coverage was a waste and what code coverage were not valuable or trustworthy.

You may see bug count go down but what % of your code coverage is or is not contributing (not useful/trustful) to that the lower bug count, and what % of missing code coverage are we missing which could make that bug count go down further.  There's way more to read into testing and especially when you go the Test Driven route.

4) You can over test

Again this comes with experience in terms of recognizing when you are doing so..testing things that don't need to be tested and adding coverage later than you didn't need.  You may not realize it until you've done TDD for a long time.   And as a result what you can end up with is having is a nightmare to where you change a line of code and have to change 200 tests, many which are not even directly related to the line of code you just changed, because your test suite is too focused or focused on stuff you don't need to be adding coverage for.

5) I find that when I Test Drive all new code, I usually end up with higher test coverage to begin with 

Rather than tack on a ton of tests after new code and hope and pray they're even valuable or wondering if I am testing the right things and that I'm hitting some goal of code coverage, I find that I end up with at least 70% code coverage most every time I TDD a new feature.  


And I'll humbly admit that this is only because I've worked my butt off to try to learn it and at the same time had the rare opportunity to pair with people who already know TDD well and learned from them how to do it the right which is why I end up with a higher percentage of valuable tests, higher test coverage, and can trust them and testing the right things but it's always a learning process...and I'm continually learning how to get better at it and always will be.

Conclusion

In the beginning, it's better to forget this code coverage goal and to learn how to do TDD right and to get comfortable with is so that you can see it's benefit which is where it starts to get fun.  This is only done through persistent practicing of it and if possible be practicing it with the right people.

When I say "right people" it's not to imply snobbiness.  It actually means the opposite, to find people who already know it well and had success with it and learn from them because it will save you a lot of pain and you'll learn ten fold and save hours of wasted time reinventing the wheel and prevent you from making common mistakes that newbies make that a seasoned TDD developer can point out and prevent you from doing or answer many questions as you go about pairing with them.  

The worst thing is for a business or team to try to become a TDD shop when there is nobody on the team who is seasoned already at TDD who can help pair and train the team for a good period of time first, and then at the same time, your dealing with the boss who just cares about goals of % of code coverage as the most important metric to deliver back to upper management for the end of the year.  You'e just going to delay focusing on what's really important, getting TDD right and seeing truly it can do for the team.

Wait till you get comfortable with TDD, and you learn how to write better tests, and start to see its value, then start worrying about coverage %.

Sunday, February 15, 2015

Windows 8 install "GPT partition style" Error and Resolution with OS X Yosemite

You're trying to setup dual boot with Windows 8 on your Macbook Pro.

You've done the following:

  • Created a bootable Windows 8 installation USB drive created by the boot camp utility in Yosemite
And after all that, you boot up and assume to select that boot-able USB drive in order to install Windows 8 with it:



But then during the Windows 8 install wizard, you select the partition you expect to be able install Windows 8 on and on the selected partition you've gotten the infamous error "Windows cannot be Installed on this disk. The selected disk is of the GPT partition style".  You try to delete the partition and attempt to recreated it and format it and yet it still doesn't rid this error.  Nothing you do works...and you're about to give up.

You've pulled your hair out a few times and you are now bald.

What do you do?

Boot up using the EFI boot partition first instead:



Once you select the EFI boot drive, it'll kick off your bootable BootCamp created USB Windows install drive and this time the windows 8 install wizard will be fine and you will not see this error when selecting your partition in which to install Windows 8 on.



I am sure I've had this very same pain before in prior Mac OSX or my previous Macbook Pro laptop, but I just did not remember.  So now I'm blogging about it so I do remember next time and so it hopefully reminds others ;).

Wednesday, December 17, 2014

Pushing Initial Code to Your Github Repository via Windows





Git is not a scary monster that is hard to learn like a lot of devs who haven't used it assume it to be.  Git is not hard to figure out.  In fact it's so easy to get up and running and use I guess you can say it's kinda scary in that respect.


And you should use it.  It's a no-brainer not to.  No it's not that "it's cool" to use Git (well sure it is), but it's that Git really changes the game and makes things flexible, friction-less, and very powerful when dealing with source control both on the server-side and client-side.  Git is awesome.  It's painless.  It's flexible.  It's fast.  It's so much more.


In the past I've mainly been a Subversion guy.  Stayed far, far away from TFS when at all possible (heavy bloated, loves to bug the hell out of you in unexpected and frustrating ways, and loves to throw little fits and do weird things).  If you don't see that TFS users, you're blind.


And really, all-in-all there's a very small set of commands you really need to master with Git...it's not bad.  Once you get it and it gets repetitive it's nothing, and you'd never go back to another source control ever.  


There are a lot of git posts out there, but I just wanted to share step by step how to take code that lives locally and push it to a new repository on GitHub and show in as much detail as I can with some print screens from my laptop.  I wanted to be a little more detailed than most posts out there and you should do your homework also, I recommend you do first and take the time to read this documentation....there's quite a bit more in there.  Read that slow, and read it well

Scenario: You have an existing project locally on your windows PC.  It's a .NET solution or whatever.  You want to use GitHub to host your project.  And this the first time you're doing all this for that particular project.  


Some of this is a repeat from GitHub docs, but I wanted to show it as a real person doing it and I want to add other things in here that will hopefully serve as a shortcut for you...by reading this post.



Install Git

  1. Download git and install it
           
         

Configure Git

When you install Git it installs also Git Bash emulator, which is what you'll use for everything with Git.  It's a shell that allows you to run both Git and Unix commands and you'll need to use both.  (The other option is to go with some heavy GUI like Git for Windows or Atlassian Source Tree, etc.)


I much prefer command-line over an all UI based Git client or a Windows Explorer context menu because command line is much quicker for getting things done once you get the very small set of commands you'll need to do the majority of commands for basic daily Git usage.  And I like to truly know what's going on when I perform operations with Git down to the bare metal because it gives me a raw understanding of Git, so I truly know what it's doing under the hood.  I don't want all things hidden behind a big GUI showing me everything done visually (by performing "black magic" behind the scenes).  I want to know the core commands of Git, it allows you to understand under the hood which makes things much more easy when you know it inside out rather than outside (GUI) hiding in.


When you first open Bash, your default context starts at "~" which in windows the context is your Home directory which is C:/Users/[YourUserName]


To cd to a directory it's a little different than the windows command prompt but not by much.  You use forward slashes, no colon or backslash.  Remember these are unix commands, not Windows command prompt.  So e.g. cd /c/www/MyProject


Tell Git Who You Are
Configure your email, name, etc.  This is what will be part of commits etc.








Setup a .gitignore File

Lets set our gitignore file which will filter out file types and folders we don't want to include in our pushes to the repository.


You could just create a file and copy definitions into it which you can get from various places on the net

OR

You could setup a nice utility like GitIgnorer.

Manually

Open Bash, this is very easy using Unix commands

Create the file:




Move the file to the root of your project directory:




Go out and find some filter definitions that fit your development environment that exclude files you don't want checked into source control.  You can find these all over StackOverflow.com, blogs, and a nice list on GitHub itself.  Then copy that text into your .gitignore file.

Setup GitIgnorer (optional)

I'm using Gitignorer a little utility that allows you to quickly and easily grab one or more .gitignore templates from GitHub and mash them as you please.  

  1. Download Gitignorer
  2. Unzip it but put the exe wherever you want.  As long as you're cd'd whatever directory you placed the exe in (have cd'd to it), it should work
First lets use a Gitignorer's "list" command to give us a quick glance of the list that lies on https://github.com/github/gitignore so we can decide which .gitignore templates we want to use.

Note that I put that Gitignorer exe in C:\users\dave\documents...not the best place but I just wanted to get this working so will move it I'm sure later to a folder that makes more sense.























Lets grab the VisualStudio.gitignore file because this really has most of what we need for .NET development and Wnidows, etc.

First lets change directory to where we want this .gitignore file to be created. 






sure enough it created the fileand there are definitions inside it:

























but whoops! I don't want it in my documents, lets move it using Unix commands

               



Ok now it has been moved.

Lets also rename it to give it more meaning because I'm gonna put more stuff in here that it already has later on


             




and now we see

There are some patterns missing that I'd like in here so I added them:




Now lets tell Git that you want this ignore file to actually be a global ignore file and then verify it's set afterwards:
                

There are a number of 3rd party utilities or apps that we could use to show diffs.  

Sometimes this is one of those rare exceptions where you might want to see the diff in a GUI but nothing else, rest in the command line.



















Setup Your Local Repository

Initialize (only done once)


We must first create a local Git repository by using the init command:

init - creates an empty local Git Repository.  That's the .git folder you see created after running this command

A git repository will consit of git objects, heads, tags, and template files.




Stage your Files

Lets try to stage our files now, which is the next step before you commit to your local git repository. 

You stage your files with the add command.

We're first make our files trackable by doing a git add which adds your files to the staging area:

Add - files are now tracked and staged to be committed

Side note
    
         Be aware that your files can be in one of two states at any time in Git:

Tracked - files that were in the last snapshot; they can be unmodified, modified, or staged
  • When you first clone a repository, all of your files will be tracked and unmodified because you just checked them out and haven’t edited anything


Untracked files are everything else – any files in your working directory that were not in your last snapshot and are not in your staging area





"." means add all files












Commit Your Files to Your Local Git Repo














Lets check the status of our files now just to be sure everything looks good:






Clean - means there are no tracked and modified files
  • Tells us which branch we're on which means that it has not diverged from the same branch on the server
  • Master is the default branch
  • Git also doesn’t see any untracked files, or they would be listed here

Lets do a diff to see what files have changed that are unstaged:





Notice when you hit enter, there is nothing returned or shown.  That's because there are no changes as expected.

And lets take a look at what we have staged:





Once again notice when you hit enter nothing happens.  Nothing because we committed our last add (staged files), we haven't done any new adds or modifications to any files yet.  So there is nothing staged, it was committed already.

You can also see your branch history via a graph:





We haven't made any changes to files yet so all you'e going to see is it note an initial commit.


Setup Your Remote Repository on GitHub

Create a New Remote Repository on Github 

Log into your GitHub account and although it's self explanatory, here's where to add a new Repo:








GitHub creates a --bare repository by default.  

Notice that after you create your repository, now you have a url for anyone can use to clone your project files.  We'll be using that to create a new SSH key against this repo:






















Create an initial SSH Key

You'll need an SSH key 
as it will be used by Git for secure communication between your local Git Repo and GitHub

But before we try and create a new key, lets check to see if our PC already has one or not:







It did not find an .ssh file so we know we'll need to create one

Copy that clone url and use it to paste into this command below






Next we'll call a command that'll go get our key and copy it to the clipboard
    




Now we'll go to GitHub to add our new key so it is aware of it:

















Push Your local git repository to your Remote GitHub Repository

Lets summarize at a top level what we did so far:
  • Ran the add command to stage our code files
  • Ran the commit command to take our staged files and add them to our local git repository (.git folder contains the repo)
  • Created a new Remote repository on GitHub
  • Created a new SSH key locally through Bash then added that key to my GitHub security section
Now we're ready to finally do our first push.  That is, commit our code to our remote GitHub repository.

However at least for me there was one snag.  I like to enable 2-factor authentication.  Where you log in but then you have to get a code from your phone and enter that as a second layer of auth.  Problem is, if you enable it, you have to setup a static access token so that you can reuse it in Git...because you can't use dynamically created access tokens for Git, that wouldn't work...they'd keep changing.

In GitHub create a new token:


























now copy that token to the clipboard:






Push Your Code to Your Remote Repository on GitHub

Finally lets push (commit to a remote repo) our code to our GitHub Repository:

** Since we enabled 2-factor auth, for your password you'll input that token, not your GitHub password.

 









And sure enough it's now on GitHub:

Now developers (or yourself) can clone (copy) and start working on it locally.