Monthly Archive: August 2013

Github

How to Collaborate On GitHub

If you don’t already know, GitHub is an incredibly effective way to collaborate on development projects. Providing a place for anyone with an internet connection to have an avenue where they can share code with the world for free (not to mention the robust supporting tools for source inspection and easy viewing of commit histories). GitHub has been adopted by many large open-source projects as their primary home for collaboration and contribution.

But how do you join in and contribute to a project? Sure, you know how to use Git to track changes to files and push those files to a server. But there are major benefits to getting involved in larger open-source projects, and GitHub is arguably the best place to start. Today, we will discuss a few rules of the road for collaborating on open source projects, and give you the knowledge and intuition you will need to get involved.


Start Small

Don’t be afraid to start small

One of the most important things to understand when getting started with collaboration on open-source projects is to recognize your role. Often, there are plenty of things you as a developer can do that don’t involve being an extremely clever programmer. In fact, fear of being an inadequate programmer is often a reason why people don’t get involved in open source projects to begin with. Don’t be afraid to start small: instead of trying to fix a major bug or rewriting an entire module, try finding things like documentation inadequacies or cross-device testing and patching, or even simple syntax errors and grammar issues (like this one from GitHub user mzgol).

These kinds of tasks are a good way to get your foot in the door as a contributor to the project without trying to take on more than you can handle. Sign up for CodeTriage to get automated GitHub Issues sent to your inbox. If one hits your inbox that you feel confident you can take on, work on it and send a pull request. (We’ll talk about how to do that a bit further down in the post.)


Learn the Ecosystem of the Project

With any collaborative effort, a set of conventions has probably been adopted. This may include a vocabulary set, a way of contributing and formatting commit messages, a certain rhythm of collaborating that the contributors have agreed to, or even syntactic standards that have been established. Before you try to get involved with a project, read all documents related to these things. For instance, GitHub has standardized a CONTRIBUTING.md file (check out the guidelines for getting involved with jQuery for a thorough example). These guides are maintained by the people who also maintain the codebase and the master branch.

Another way of understanding the ecosystem of a project is to simply look at the existing codebase and the git log. Reading through the commit messages and perusing the code style can tell you a lot about a project. Read through the project’s documentation, and adopt the vocabulary used so that your contributions maintain continuity and portray a similar voice.

Once you’re part of the project’s cultural ecosystem, how do you actually contribute code?


The Pull-Request Workflow for Code Contribution

The workflow for contributing code can seem daunting at first.

The workflow for contributing code can seem daunting at first. The most important thing to remember is to follow the patterns and standards outlined by the project you are working on (as we have already discussed). The general workflow that GitHub supports is fairly simple.

  1. Fork the target repo to your own account.
  2. Clone the repo to your local machine.
  3. Check out a new “topic branch” and make changes.
  4. Push your topic branch to your fork.
  5. Use the diff viewer on GitHub to create a pull request via a discussion.
  6. Make any requested changes.
  7. The pull request is then merged (usually into the master branch) and the topic branch is deleted from the upstream (target) repo.

Within this workflow, you may see many variations for any given project. For instance, the naming conventions for topic branches vary. Some projects use conventions like bug_345, where 345 is the ID # of a GitHub issue that has been filed. Some projects prefer shorter commit messages than others. Here is a series of commands that would complete the workflow above.

Step 1: Forking

Fork the repo on GitHub.com

github_header
forking

Step 2: Cloning

Clone the repo using the URL in the right sidebar:

git clone git@github.com:jcutrell/jquery.git
clone_url

Step 3: Adding the Upstream Remote

Change into the cloned directory and then at this point, you can add the upstream remote:

cd jquery
git remote add upstream git@github.com:jquery/jquery.git

This will now allow you to pull in changes from the source locally and merge them, like so:

git fetch upstream
git merge upstream/master

Step 4: Checking Out a Topic Branch

However, before you make your own changes, checkout a topic branch:

git checkout -b enhancement_345

Step 5: Committing

Now, you can make your changes, and create a commit that tracks just those changes.

git commit -am "adding a smileyface to the documentation."

Step 6: Pushing

Next, you’ll push this topic branch to your own fork of the project.

git push origin enhancment_345

Step 7: Creating a Pull Request

Finally, you will create a pull request. First, go to your fork of the repo. You might see a “your recently pushed branches”, and if so, you can choose “Compare and Pull Request”. Otherwise, you can select your branch from the dropdown, and subsequently click “Pull Request” or “Compare” at the top right of the repo section.

compare_pull_request
Creating a pull request via the Compare and Pull Request button.
switch_branches
Creating a pull request via the branch dropdown menu.

Either of these will take you to a page where you can create a pull request and comment on the request. This page also includes a visualization of the changes you made. This makes it easy for the project administrator to see what you have done and make easier decisions about whether it is appropriate to merge your commit. If they have questions, they can ask them in the comments; they may also ask you to clean up your pull request and resubmit, and subsequently close the pull request.

Note that it is incredibly important that you show the administrators of a project full respect; after all, you can always use your forked version of the code, and if they chose not to pull in your changes, it is because they have the position to do so. Remember, according to Github Employee Zach Holman‘s take in “How GitHub Uses GitHub to Build GitHub”, pull requests are conversations. This is how they should be treated; instead of expecting your commit to be accepted, you should expect only that it will open conversation about the code that you wrote.


GitHub Issues + Pull Requests = Project Management Zen

GitHub offers GitHub Issues, which is a robust way of creating documented, interactive, automated conversations about bugs or features for any given project. While Issues can be disabled, they are enabled by default. There are a lot of awesome features that Issues has built-in, but one of the most important features is its integration with pull requests. A user can reference an issue in their commit message by simply including the issue’s numerical ID in the commit message. For instance:

git commit -am "Adding a header; fixes #3"

This commit message would automatically mark issue #3 as closed when its associated pull request is accepted. This kind of automation makes GitHub a wonderful tool for development project management.


Seek Out Secondary Channels of Collaboration

Often, large open-source projects benefit from many different kinds of collaborative work.

Don’t get caught up thinking that the only way you can contribute is through pull requests. Often, large open-source projects benefit from many different kinds of collaborative work. For instance, a project like Ruby on Rails was notorious for its community; this community would answer questions on forums and in IRC chatrooms to help build knowledge about the framework, and also would help drive the future direction of the framework by talking about ideas and uncovering bugs.

These channels of collaboration are usually opened up as support environments as mentioned before, such as forums and chatrooms. There may also be email chains, meetups, or conference calls that help define the project’s direction and create a lively, productive community around the project. Without this kind of community, pull requests are far less effective.


Most of All, It’s About Your Attitude

Remember, open source is driven by people who have the attitude that sharing knowledge and building collaborative intelligence is a worthwhile endeavor. Your involvement in these projects will be most effective if you approach a given project with the inquisitive attitude that asks “how can I help?” rather than a closed attitude that says “I’m going to help however I want.” People in the open source world want to work with people who are genuinely driven to help others.


Conclusion

If you are interested in getting involved in an open source project, great! Remember, if you approach the project with the right attitude and start small, you could see your name on pull requests merged into code that is distributed to people all over the world and used every day. Take the time to learn about the project and the people who are involved with the project. Develop a genuine interest in helping the project become better. The power of GitHub and the open-source world is continuing to grow every day; start collaborating with other developers, and you can be a part of that world!

(more...)

Wordpress

Anatomy of a Perfect Sidebar

This entry is part 1 of 1 in the series Anatomy of a Perfect Sidebar

Admit it: Most of us see sidebars as nothing more than a simple container that holds stuff, in our blogs and websites. It gets our minimum effort on the design process and we fill it up without thinking which widget should go where.

But for a well–designed website, the designer should consider a number of factors when working on them. For example, consider the number of sidebar containers, the width and height of sidebars, the order of the elements that go into the sidebars and so on.

In this post, we’re going to study the anatomy of the “perfect sidebar”.


The Definition and the Importance of the Sidebar

First things first — we need to define what a “sidebar” is:

A sidebar is a graphically separated section that contains informational and navigational parts of the website.

Granted, I cheated off from Wikipedia’s definition of the term “sidebar” a little bit.

Sidebars hold contextual elements to the content or the whole of the website, like navigational menus, search forms, or subscription widgets. They may also hold non-contextual elements like advertisements or “daily quotes”. They’re almost always narrower than the content section to emphasize that the content is more important than the sidebar. Their main purpose is to help the visitor to understand and navigate the website better.

As a content management system, the WordPress platform considers sidebars as “widget areas” where WordPress theme developers should allow WordPress widgets to be displayed in their themes.

Although they’re not technically “side” bars, the widget areas that belong to the “footer” of the theme could also be considered as “sidebars” since, well, they’re also widget areas.

For the sake of naming things properly, they should be called “footer widget areas” but in this article, we’re going to talk about them, too.


How Many Sidebars Should Be Used in a Theme?

As you might have already guessed, there’s no right answer to this question. Depending on your website’s complexity and the need for sidebar elements, it could be one to four – or none.

Single Sidebar

Single column sidebar design example: Twenty Twelve WordPress Theme
Single column sidebar design example: Twenty Twelve WordPress Theme

A single sidebar is probably the most popular choice for a blog design. And since blog pages tend to be long with the post lists or post content and comment lists, a single sidebar can hold 5 to 10 sidebar elements. Don’t forget, though: If your sidebar exceeds the height of the main content area, it will definitely seem ugly.

The sidebar can be on the left side of the main content area or on the right side. There’s no significant difference between the two but since people read left to right, left sidebars can attract more clicks while decreasing the importance of the main content, thus lowering the visit duration of each page. (The other way around goes for the RTL languages like Arabic or Hebrew.)

Two Sidebars

Two column sidebar design example: Seventeen WordPress Theme
Single column sidebar design example: Seventeen WordPress Theme

Two sidebars could be useful for corporate websites or magazines, since they should be displaying more navigational & informational elements than blogs. The downside of having more than one sidebar is that you need more space for them and that means you have to narrow down your main content area. Although, you can still enjoy two sidebars with a responsive approach: On screens narrower than a standard laptop (1366 pixels wide), you can take one of the sidebars under the other one.

Also, you can design one of the sidebars very narrow to hold some icons or one–word links, too; but, if you design it poorly, the unevenness could bother your visitors.

Three or Four Sidebars

Four column sidebar design example: SmashingMagazine.com
Four column sidebar design example: SmashingMagazine.com

This one goes without saying: You have to use responsive design techniques for this. Unless you want to annoy your visitors with screens smaller than 1600 pixels, you need to collapse or move the sidebars for narrow screens.

Smashing Magazine’s current design is one of the best examples for four column WordPress designs with a responsive approach. As the screen narrows down; the leftmost sidebar which holds the main navigation becomes the top navigation, then the second left sidebar gets under the first one on the top, then the main sidebar on the right disappears completely while the second left sidebar gets back to its original place, and finally the second left sidebar joins together with the leftmost sidebar on the top as the main navigation (which is activated with a button).

No Sidebars

Sidebarless design example: Beyn.org
“Sidebarless” design example: Beyn.org

Minimalism could be the right answer for any kind of website. If you’re into that, you might want to reconsider which sidebar elements you want to display and which ones to eliminate from your design.

Then, you can display those elements at the bottom of your pages. You can also try displaying them on the top but that could risk the main content area to be below the “fold” — you must consider the height of visitors’ screens, too.

The theme above is a theme of mine, designed for my blog, Beyn. I always used/coded themes with a single sidebar for Beyn but with this new theme, I wanted to try a “sidebarless” design and it worked out beautifully: At the bottom of every page, I only have three widgets: An “announcements” list, a list of email/feed/social subscription buttons and a “latest comments” widget.

The benefit of a “sidebarless” design is your main content drawing the most attention possible.


To Be Continued…

This is the end for part one of this series. We will be covering subjects like the two dimensions of the sidebar, ordering of the elements and other issues to consider (like colors, images and font sizes) in the next part.

(more...)

Design

Choosing a Grid System

In the previous article, I introduced you to grid systems. With any luck, by now, you should have a good understanding of what they are and why they’re a good weapon to have in your design arsenal.

Today, I’m going to explain about choosing a grid system – from creating your own, to working with pre-made CSS frameworks. By the end of this article, you’ll have a good idea of the way you might like to walk your path with grid systems – and hopefully feel confident enough to do so.


Our Choices

Let’s begin by narrowing things down.

Framework or D.I.Y.?

We have two choices before us: do we go with a pre-made framework that somebody else has already built, or do we create our own grid system and work with that? Really, the answer is all down to your personal preference.

I would always recommend that if you’re just starting out with designing for the web, then it may be more beneficial for you to start designing with pre-made frameworks. These designs don’t have to be permanent and can instead be a way of you working with grid systems in a way that eases pressure and allows you to experiment and understand them more.

The 960 Grid System

The 960 Grid System

Pre-made frameworks also allow you to work with prototyping a design – where we can quickly bolt together different elements and modules in a design to see how these play out when they’re actually in a browser (in as realistic a way as they can get, being on a digital form such as the web).

However, I always think that it’s best to create your own grid, if you ever can do so. This way, you’re not only much more in control of the design and structure of your grid, but you can then also be much more in control over the output of your grid and how this plays out in the development stage of your website design. And I don’t know about you (though I imagine many developers will feel the same way I do) but I like to have every bit of control I can have over my code and how it’s presented; creating my own grids allows me to do just that.

Pre-Made Frameworks

Pre-made frameworks are found aplenty in the web design world – what seemingly started out with one or two grid systems (such as 960.gs) soon blew up to us having many dozens, if not hundreds, of grid systems available for us to use.

Grid frameworks are useful as they allow us to easily get a prototype or basic website in place when we’re developing. However, how can we switch that so they’re also useful when we’re designing?

Pre-built frameworks will often come with some sort of PNG or PSD for you to use when you’re designing – and if not, then you’ll need to try and replicate this grid into your design. Simply create a new layer and put this grid overlay in place. Then, you can start designing to the grid that you have.

The responsive Golden Grid System

The responsive Golden Grid System

Popular grid frameworks include

D.I.Y. Grids

Just as when I’m working with my code, I like to have control over what I’m designing. If I work with a premade grid framework, then in a way I am committing my work to somebody else’s preferences – whereas if I design my own grids, it means that I have all of the control over how my grid works, how it relates to my design and I know I will have much more control over the final code output as well, as I will have designed it.

Although it can seem quite daunting, as long as you’re armed with some knowledge, creativity and ideas of a layout for your website, then creating your own grids needn’t be as scary as it sounds.

Creating your own grids is hard when you haven’t done it before – but there are so many tools out there to help you. Up until a few of these tools came out I hadn’t even tried creating my own grids myself and I was a big fan of frameworks – but seeing the advantages of being able to create my own grids for every project I do has made me feel much more creative. I feel I can come up with more more innovative and unique design ideas.

First up, when you’re designing your own grids, continually return to your sketchbook, making a few sketches and ideas of layout. Even if you just go back to some of your initial sketches that you made at the beginning of the project, imagining how these sketches can fit into a grid can be useful and give you a head-start.

Creating your own grids is also about a lot of theory – and far too much to include here, for it could be a massive session of articles on its own! But try to master the basics first. Look at your favourite websites online and see if you can pick out a modular or grid-like pattern to their design. See if you can look at the designs you admire and see how different elements align, how the grid might adapt when the design is scaled up or down responsively – all those sorts of little things will help your understanding of using and creating grids much better.

Tools to Create Your Own Grids

As I said before there are many, many tools available to you for creating your own grids to use in your web designs. I’ve picked just three popular solutions, that have helped me the most when rolling with my own grids, but be aware that there are many more just a Google search away.

Gridset

Gridset is a wonderful tool, created by the lovely folk at Mark Boulton Design Studio in South Wales.

From Mark Boulton Design, Gridset App

From Mark Boulton Design, Gridset App

In their own words, Gridset is simply a “tool for making grids” – and they make it so easy to do so. Gridset is perfect for all stages of creating and using your own grids – designing, prototyping and production-stage development.

To create your own grids with Gridset, you simply create a gridset and then create different grids for each of the major breakpoints you think you will use in your design. You can alter the column width, gutter width and even change the ratio of the columns – plus much more.

Gridset provides you with a PNG grid overlay you can use when designing, you can add classes to your HTML to prototype quickly and you can use the measurements that Gridset calculates in your own markup (so you don’t have to use the provided Gridset classes).

With Gridset, you can also use their built in Sass functions – making it even easier to integrate your grid design into your development workflow.

One other great thing about Gridset is the wealth of information they provide about grids. I found I learned so much just through the Gridset blog and deciphering the Gridset Specimens they have on their homepage.

Gridpak

Gridpak is one of the first really interactive responsive grid making tools I found online, created by Erskine Design in Nottingham.

From Erskine Design, Gridpak.

From Erskine Design, Gridpak.

Gridpak works by creating a number of grids (by defining a column size, column padding and gutter widths) for your custom breakpoints.

Once you’ve created all of your grids in Gridpak, you’ll get a download with all the files you’ll need to integrate your grids in your website workflow – a PNG to use as a grid overlay when you’re designing, several files you can use for your Gridpak grid CSS (“vanilla” CSS for your standard classes, as well as both a LESS and Sass version) and you also get a JavaScript overlay file that you can use to overlay your grid on your websites during development.

Gridpak seems really useful to me for prototyping more than anything – it’s really quick to get some visual representations of your grid (at particular responsive breakpoints, too) and integrate these into a quick prototype. From there, we can look at spending more time refining the provided CSS classes into our own markup, ensuring that the quality of our code (which should always be important to a developer!) is top-notch.

CSS Wizardry Fluid Grids

If you don’t want all the bells-and-whistles and instead you’re just after a quick calculator that will help you to create some responsive grids – then I’d receommend a trip to Harry Roberts’ Fluid Grids.

From Harry Roberts (CSS Wizardry) the Fluid Grids Calculator.

From Harry Roberts (CSS Wizardry) the Fluid Grids Calculator.

While he can’t host this on his own website anymore (due to the setup he now has), Harry has kindly popped up the original code on to Github. You may have to perform a little manual work to get this working, but it’s well worth the effort if you want a quick and easy system to setting up your grid framework and design.


Assignment

Now you know all about grids and some of the tools you need when creating grids – I want you to try your hand at making some of your own! Using any of the tools mentioned above – or indeed using your own, if you’ve already developed one. Try your hand at creating some of your own grid systems and starting to integrate them with your designs. Let us see the results in the comments!

(more...)

CSS

Getting Started with the Sass Preprocessor

Preprocessors are a popular way of simplifying and writing more manageable CSS, as well as making use of frameworks to write better CSS. Let’s take a look at the basics and learn how to create a fully loaded CSS3 button with gradients, shadows and transitions while making use of the Sass preprocessor and Compass framework […]

(more...)