Troubleshooting

Monday, 3 October 2016

This lab session will be primarily dedicated to helping you work out kinks and wrinkles in the process of getting your site online and completing the second assignment. If you are already very far along, then this is an opportunity for you to finish your work.

Q&A

• Who's close to done?

Testing

In software development it's very important to actively test your work. Here are some basic user tests you should do on your site:

• Can I see the post(s) from the index of the site?
• Can I navigate to the pages from there?
• When I navigate to each page, does it display correctly?
• When I navigate to each post does it display correctly?
• Is all of the information in my layouts (twitter, email, copyright, etc) correct for me? (if not, fix or remove it)

Ideally your development environment replicates production to the point that you don't need to test in both places. But, especially in the beginning, it's important to make sure that all your links, etc. work on github.io like they do in your c9users.io site.

Troubleshooting

In addition to completing your site and the assignment at hand, we will start looking at ways that you can teach yourself how to fix problems that happen. You will always run into issues, no matter what you are working on. This will never stop. Getting good at resolving issues that come up is synonymous with being a coder.

At that point, you have two options:

1. Wait for someone to help you.
2. Figure it out on your own.

Guess which one goes further in the course of your academic and work lives.

Sources of information are myriad

It is really difficult to recommend places to get help with troubleshooting online. This is not because they are so few, but because they are so many.

The best approach is to actually see what information you can get directly from the error interaction and then move on from there.

Read the error and try to understand it in plain language. That may work some of the time.

Some error systems give VERY helpful errors that include suggestions for ways to fix what has gone wrong. Git is like this. If you have a git error, most of the time, it will tell you what has gone wrong and how you can fix it. Usually you just have to read it and do what it says. Though, make sure that you don't just blindly do what it says. Sometimes you're trying to do something you shouldn't like commit changes to the _site directory and it is just helping you do that.

Sometimes error messages will be more obtuse: this is a legitimate and well-known fact.

If you catch an error that doesn't make sense to you, try at the very least to figure out what it means or to what it is referring.

Google it

Take this error, for example:

error: Entry '<fileName>' would be overwritten by merge. Cannot merge. (Changes in staging area)

This is not particularly helpful. I could pore over the git documentation for this, or I could take a more reasonable path and Google it.

As you can see, there is a fair amount of information immediately available that will help you cirvumvent that error.

Take this approach first and keep these things in mind:

1. Be careful: not all information is good.
2. Learn to spot the difference.
3. READ.

Stack Overflow is generally a useful resource for recovering from errors. It is well curated and lots of people use it to figure things out.

Jekyll errors

Keep an eye on your Jekyll process. It will spit out errors there that may explain why your site isn't showing up the way you expect it to. Remember, some times you'll need to restart your Jekyll process if you've changed the way it should set itself up.

Merge Conflicts

If you're unable to git push, this usually means you somehow got commits up to Github that aren't on your current branch. You'll need to git pull to merge those commits, then you can git push. If git can't automatically figure out how to merge the changes, it will tell you where the conflicts are and you'll need to merge them yourself. Merge conflicts can also happen when you try to merge a local branch.

Basically, just keep calm and make all the files look the way they should. Git will insert a bunch of ugly <<<<<<<<, ============= and >>>>>>>>>> to help you see the conflicts. Delete all of this and leave only the version of the enclosed code you want to keep.

More:

• Basic walkthough
• Github's merge conflict docs

Swakifying Your Site

Many of you are very far along with your sites. Don't stop experimenting! Here are some ideas for you to keep improving your site even after the standard

• Basic: Add links to resources you've found outside of class that you think are helpful.
• Intermediate: Add a hosted photo album to your page as an embed, with digrams or other images you found helpful from the class
• Advanced: Add JQuery powered sparkles to your site. For this to work, you'll need some <script> tags to load Jquery, this library, then some javascript telling this library what HTML elements to make sparkle. JQuery is just Javascript, but a little easier to read and write. You select elements by putting a CSS selector somewhere, like this code selecting all h1 elements:

$("h1").sparkle();

The .sparkle(); tells the library we loaded to make the element sparkle. You'll need to tell Javascript when to do this, so add this <script> element to the very bottom, before the </body> close tag:

<script>
  $(document).ready(function() {
    $("h1").sparkle();
  });
</script>

That should make h1 elements sparkle when you mouse over them.

For Next Time

Keep working on your sites! Weds your Assignment 2 is due and that class will be the last chance I have to help you so bring your questions! I'll probably have an optional activity for those who are done and want to swankify further.

• troubleshooting
• websites
• trial-and-error