github-roam.md

Foreword

About the Author

Phodal Huang (Huang Fengda) is a maker, engineer, consultant, and author. He graduated from Xi'an University of Arts and Science with a major in Electronic Information Engineering and currently works as a consultant at ThoughtWorks Shenzhen. He is an active contributor to the open-source community on GitHub, focusing on the Internet of Things and front-end development.

As an open-source software author, he has created software such as Growth, Stepping, Lan, and Echoesworks. Among them, the open-source learning application Growth has been widely praised by readers and users and is available for download on the App Store and major Android app stores.

As a technical author, he has written DIY IoT Design (Electronic Industry Press) and Full-Stack Application Development: Lean Practice (Electronic Industry Press, currently being published). On GitHub, he has open-sourced seven e-books, including Growth: A Guide for Full-Stack Growth Engineers and GitHub Roaming Guide.

As a technical expert, he has reviewed IoT books such as Learning IoT and Smart IoT, as well as front-end books such as Angular 2 Services and Getting Started with Angular for the UK publisher Packt.

He loves programming, writing, design, traveling, and hacking. You can learn more about him on his personal website: https://www.phodal.com/.

Other relevant links:

• Weibo: http://weibo.com/phodal
• GitHub: https://github.com/phodal
• Zhihu: https://www.zhihu.com/people/phodal
• SegmentFault: https://segmentfault.com/u/phodal

This is a preview version. If you encounter any issues while using it, please feel free to contact me. For questions during reading, consider raising them on GitHub: Issues.

If you encounter grammatical errors, spelling mistakes, technical errors, etc., during reading, feel free to submit a Pull Request to help other readers of this e-book.

My E-books:

• GitHub Roaming Guide
• My Profession Is Front-End Engineer
• Serverless Architecture Application Development Guide
• Growth: A Guide for Full-Stack Growth Engineers
• Phodal's Idea Practical Guide
• Step-by-Step IoT System Building
• RePractise
• Growth: Full-Stack Growth Engineer in Action

My WeChat Official Account:

My GitHub homepage shows the join date—Joined on Nov 8, 2010. I was just a freshman at the time and didn't log in for a long time after that. Perhaps because I didn't major in computer science, it wasn't until today—2015.3.9—that I realized this is actually a social network for programmers.

In the past, I spent a long time trying to maintain a streak on GitHub and learning how others used this tool effectively. Of course, followers are also very important on GitHub.

Here, I will try to share everything I've learned on GitHub, one by one.

My Story with GitHub

When I was looking for a job in my senior year, I tried to find a job related to hardware or the Internet of Things (my major was Electronic Information Engineering). Even though my resume was filled with various experiences and skills, it was of no use. After attending several campus recruitment fairs, I didn’t submit any of the ten resumes I prepared—because my school was directly rejected. I had no interest in gatecrashing interviews; a thousand-mile horse needs a Bole. Later, I joined the company where Martin Fowler worked, but that’s another story.

This is a cruel world. In your student years, if you’re not handsome or tall, most additional skills are useless (though those who are rich probably won’t read this article). During your career, if your previous employer isn’t well-known, it will affect your compensation in your next job. However, many things can change this, and GitHub is one of them.

I registered for GitHub around my freshman year but only became familiar with it in my senior year. Now, I’ve been out of college for a year. In the past two years, I’ve tried creating projects on GitHub in several dimensions:

1. Quickly learning frameworks through practical demos.
2. Refactoring others’ code.
3. Creating frameworks I can use.
4. Quickly building large-scale applications.
5. Building general-purpose frameworks.

GitHub and Rewards

Let’s start with rewards unrelated to skills. My graduation project was Minimal IoT System. Considering that our major’s teachers lacked knowledge in this area, which could cause issues during the defense, I tried to align the project with their expertise. After graduation, this project had over a hundred stars. Such beginner-friendly projects are quite popular (though hardware-related projects are often limited by the relatively small number of hardware developers on GitHub).

A month after graduation, I received an email from PACKT Publishing (they found me on GitHub) about reviewing an IoT book, specifically Learning Internet of Things, mentioned in From Reviewing to Translating IT Books. As an "IoT expert" who hadn’t even passed CET-4, reviewing an English IoT book was a challenge.

Of course, I finished the review, and the book included my English bio.

A month ago, I received an email from MANNING Publishing (again, via GitHub) about reviewing the table of contents for an IoT book and providing suggestions.

This brought more opportunities, though that’s not the focus here. Let’s not discuss various spam emails or Chinese collaborations. I never imagined I could have a small presence in the English-speaking world.

This tells us that if you find a topic you’re good at on GitHub, many people will seek you out.

GitHub and Growth

I once wrote an article titled How to Improve Yourself Through GitHub. Now, I only want to emphasize three points:

1. Testing.
2. More testing.
3. Even more testing.

Projects without tests are nonsense, unless your project consists of a single function that returns Hello, World.

If your project has thousands of lines of code and you can ensure 95% test coverage, your project won’t have overly complex functions. Even if such functions exist, they will be covered by tests.

If you’re dedicated to the project, you’ll try to improve poorly written code through refactoring. Over time, your skills will continuously improve. You’ll start exploring more advanced topics, such as stubs, mocks, and fake servers.

One day, you’ll find you can’t live without tests.

Then, you’ll believe: Projects without tests are just playing around.

Why You Should Dive Deeper into GitHub

We’ve already discussed what we can gain from GitHub. Starting to experiment means we already know the potential benefits. We’ve mentioned many examples of self-improvement, but let’s talk about other aspects.

Convenience at Work

We can gain different knowledge, content, and information from GitHub. Everyone can learn from others’ code. When we need to build a library, we can find different libraries and code to implement our functionality. For example, when implementing a library, I often find components on GitHub:

• Promise support.
• Class implementation (since there’s no good way to use classes).
• A simple template engine.
• Router for page routing.
• Basic Ajax Get/Post requests.

Landing a Job

More and more people are getting jobs because of GitHub, as their work aligns with certain companies’ needs. These companies, while searching for code, may invite them to join.

Thus, finding suitable candidates on GitHub has become a trend.

Expanding Connections

If we want to create better and more robust frameworks, knowing more people can be incredibly helpful. Sometimes, this can lead to job opportunities, similar to the previous point.

Introduction

GitHub

According to Wikipedia:

GitHub is a web-based hosting service for version control using Git. It is primarily used for computer code. It offers all of the distributed version control and source code management (SCM) functionality of Git as well as adding its own features. It provides access control and several collaboration features such as bug tracking, feature requests, task management, and wikis for every project.

And from the official introduction:

GitHub is the best place to share code with friends, co-workers, classmates, and complete strangers. Over eight million people use GitHub to build amazing things together.

What else is it?

• A website.
• A free blog.
• A profile manager.
• A resource collection.
• A resume.
• A code snippet manager.
• A programming environment host.
• A writing platform.

And more. It seems like a feast, but what else do you need to know?

Version Management and Software Deployment

jQuery¹ released version 2.1.3 with 152 commits. We can see commit messages like:

• Ajax: Always use script injection in globalEval … bbdfbb4
• Effects: Reintroduce use of requestAnimationFrame … 72119e0
• Effects: Improve raf logic … 708764f
• Build: Move test to appropriate module fbdbb6f
• Build: Update commitplease dev dependency
• ...

GitHub and Git

Git is a distributed version control system designed to handle everything from small to very large projects with speed and efficiency. It was created by Linus Torvalds for Linux kernel development.

GitHub hosts Git repositories and provides a web interface, but unlike services like SourceForge or Google Code, GitHub’s unique selling point is the ease of forking projects. Contributing to a project is simple: click the "fork" button, check out the code, make changes, and submit a pull request. Some have called GitHub the MySpace for coders.

Using GitHub Effectively

How to use GitHub effectively and practice agile software development is an interesting topic. We can do many things on GitHub, from testing to CI, to automated deployment.

Agile Software Development

Obviously, I’m exaggerating; this has little to do with agile software development. But I don’t know much about waterfall development either. Let’s talk about what I know about project composition:

• Kanban-style application management (like Trello).
• CI (Continuous Integration).
• Test coverage.
• Code quality (code smell).

For a non-remote team (e.g., a one-person project), Trello, Jenkins, and Jira aren’t necessary:

You exist, deeply in my mind.

When you’re alone, you just need to know what you want. What we need are CI and testing to improve code quality.

Testing

Usually, we look for documentation. If there isn’t any, what do you do? Look at the source code or the tests?

it("specifying response when you need it", function (done) {
    var doneFn = jasmine.createSpy("success");

    lettuce.get('/some/cool/url', function (result) {
        expect(result).toEqual("awesome response");
        done();
    });

    expect(jasmine.Ajax.requests.mostRecent().url).toBe('/some/cool/url');
    expect(doneFn).not.toHaveBeenCalled();

    jasmine.Ajax.requests.mostRecent().respondWith({
        "status": 200,
        "contentType": 'text/plain',
        "responseText": 'awesome response'
    });
});

Source: https://github.com/phodal/lettuce

The test case above clearly explains the usage, even if it’s a bit rough.

Wait, what is testing for? Let’s talk about why I wanted to write tests:

• I don’t want to manually test each feature every time I finish a new one (automated testing).
• I don’t want to refactor and accidentally break existing functionality without realizing it.
• I’m afraid to push code because I’m not confident.

Although I’m not a die-hard TDD fan, the purpose of testing is to ensure functionality works. TDD doesn’t necessarily help us write higher-quality code, but sometimes it’s useful for writing simpler logic.

Maybe you already know frameworks like Selenium, Jasmine, Cucumber, etc., and have seen tests like:

 Ajax
   ✓ specifying response when you need it
   ✓ specifying html when you need it
   ✓ should be post to some where
 Class
   ✓ respects instanceof
   ✓ inherits methods (also super)
   ✓ extend methods
 Effect
   ✓ should be able fadein elements
   ✓ should be able fadeout elements

Source: https://github.com/phodal/lettuce

Each test seems small, but after completing all tests, we get test coverage:

File	Statements	Branches	Functions	Lines
lettuce.js	98.58% (209 / 212)	82.98% (78 / 94)	100.00% (54 / 54)	98.58% (209 / 212)

After local tests pass, we add Travis-CI to run our tests.

CI

Although Node.js isn’t strictly a language, since we’re using Node, here’s a simple .travis.yml example:

language: node_js
node_js:
    - "0.10"

notifications:
    email: false

before_install: npm install -g grunt-cli
install: npm install
after_success: CODECLIMATE_REPO_TOKEN=321480822fc37deb0de70a11931b4cb6a2a3cc411680e8f4569936ac8ffbb0ab codeclimate < coverage/lcov.info

Source: https://github.com/phodal/lettuce

After integrating this into README.md, we get the earlier diagram.

CI is crucial for developers working on the same project from different locations, as it ensures project robustness when new features are added with test coverage.

Code Quality

Tools like jslint only ensure syntax correctness but don’t guarantee you won’t write code with bad smells, such as:

• Duplicate code.
• Overly long functions.
• Etc.

Code Climate is a tool integrated with GitHub that provides insights into test coverage and code quality.

Let’s look at the earlier Ajax class:

Lettuce.get = function (url, callback) {
    Lettuce.send(url, 'GET', callback);
};

Lettuce.send = function (url, method, callback, data) {
    data = data || null;
    var request = new XMLHttpRequest();
    if (callback instanceof Function) {
        request.onreadystatechange = function () {
            if (request.readyState === 4 && (request.status === 200 || request.status === 0)) {
                callback(request.responseText);
            }
        };
    }
    request.open(method, url, true);
    if (data instanceof Object) {
        data = JSON.stringify(data);
        request.setRequestHeader('Content-Type', 'application/json');
    }
    request.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
    request.send(data);
};

Source: https://github.com/phodal/lettuce

Code Climate highlights several issues:

• Missing "use strict" statement. (Line 2)
• Missing "use strict" statement. (Line 14)
• 'Lettuce' is not defined. (Line 5)

These are minor issues, but sometimes you might see:

• Similar code found in two :expression_statement nodes (mass = 86)

This indicates duplicate code that can be refactored.

Refactoring

I won’t delve too deeply into refactoring here. Refer to Martin Fowler’s Refactoring for details.

The key point is that refactoring can only be done safely if the code is covered by tests.

Creating Open-Source Projects

People create open-source projects for various reasons, but the process is generally the same.

1. First, we need to name our project.
2. Then, choose an appropriate LICENSE for our open-source project.
3. Finally, create the project.

Choosing a Good Name

Naming is never easy.

So, to keep it short, choose a meaningful name—though it’s fine if it’s not.

Generally, if you plan to have a series of open-source projects, maintain a consistent naming convention.

Choosing the Right LICENSE

In the late 1970s and early 1980s, to prevent their software from being used by competitors, most manufacturers stopped distributing source code and began using copyrights and restrictive software licenses to limit or prohibit copying or redistribution of source code. Later, Richard Matthew Stallman (RMS) initiated the free software movement, introducing the concept of Copyleft: using copyright law principles to protect the rights to use, modify, and distribute free software. He is the primary author of free software licenses like the GPL (widely used free software license). ²

(PS: For more information and history about free software and RMS, read Free as in Freedom: Richard Stallman's Crusade for Free Software.)

Later, the concept of open-source software emerged, with slightly looser requirements than free software³. All free software source code released to date is open-source, but not all open-source software is free. This is because different licenses grant users different rights. For example, the GPL requires modifications to be open-sourced, while the more permissive MIT license does not.

Below is the market share and usage of different open-source licenses:

For example, in some foreign books with accompanying code, the author usually specifies the copyright of the code in the preface or a similar section:

You may need to use the code from this book in your programs or documents. Unless you are using large portions, you don’t need to contact us for permission. For example, using a few snippets from this book to write a program does not require permission, blabla.

Thus, choosing an appropriate LICENSE becomes an interesting topic. To help, I created a flowchart for open-source license selection:

Simply put, these licenses differ in terms of rights. For example, placing code in the public domain means anyone can modify it without attribution. If you want attribution, use the MIT license. If you want to allow closed-source modifications, use the MPL, etc.

Let’s briefly introduce a few common licenses.

Public Domain

WTFPL (Do What The Fuck You Want To Public License) is a rarely used, highly permissive free software license. Its terms are essentially equivalent to dedicating the work to the public domain. ⁴

This means anyone can modify the code as they see fit.

GPL

Due to the infectious nature of the GPL, anyone using our code must also open-source their modifications under the GPL. In other words, the GPL is a "viral" license.

If we only want others to use the library without open-sourcing their modifications, we can use the LGPL. However, modifications to the library itself are not exempt.

MIT

Thus, I generally use the MIT license. At least it retains attribution rights—you can modify my code, but you must include my name in the LICENSE.

Using MIT is particularly interesting, especially in recent years, with incidents like:

• iView "plagiarizing" Element UI
• AndroidTVLauncher "plagiarizing" incident

This teaches us: if you don’t want such experiences, don’t use MIT.

Creative Commons

Yes, when I write Markdown, considering it might appear in print form, I use the CC-BY-NC-ND license:

• CC -> Creative Commons
• BY -> Attribution
• NC -> NonCommercial
• ND -> NoDerivs.

This means anyone can freely copy, distribute, display, and perform the work but not for commercial purposes (except the author). It can be freely posted on blogs or articles but must be attributed, and the work cannot be altered.

If you don’t mind, you can use the public domain. But if someone publishes your work as a book, you might regret it.

Git Basics and GitHub Usage

Git

From a developer’s perspective, Git offers the following functionalities:

1. Clone a database (including code and version history) from a server to a local machine.
2. Create branches, modify code locally.
3. Commit code on local branches.
4. Merge branches locally.
5. Fetch the latest code from the server and merge it with the main branch.
6. Generate patches and send them to the main developer.
7. Address feedback from the main developer. If conflicts arise between developers, they must resolve them before submission.
8. Developers can use the pull command to resolve conflicts among themselves.

From a maintainer’s perspective (assuming they don’t write code), Git offers:

1. Review emails or other notifications for developer submissions.
2. Apply patches, resolve conflicts (either independently or by asking developers to resolve them).
3. Submit results to the public server and notify all developers.

Getting Started with Git

If using Git for the first time, set your name and email:

$ git config --global user.name "Your Name"
$ git config --global user.email "your.email@example.com"

Clone a repository to your local machine:

$ git clone git@github.com:someone/symfony-docs-chs.git

Now you can modify the code locally. After making changes, stage them:

$ git add .

Or add specific files:

$ git add -p

Check the current status:

$ git status

You’ll see changes from yellow (unstaged) to green (staged).

GitHub

According to Wikipedia:

GitHub is a web-based hosting service for version control using Git. It is primarily used for computer code. It offers all of the distributed version control and source code management (SCM) functionality of Git as well as adding its own features.

And the official introduction:

GitHub is the best place to share code with friends, co-workers, classmates, and complete strangers. Over eight million people use GitHub to build amazing things together.

What else is it?

• A website.
• A free blog.
• A profile manager.
• A resource collection.
• A resume.
• A code snippet manager.
• A programming environment host.
• A writing platform.

And more. But what else do you need to know?

Version Management and Software Deployment

jQuery¹ released version 2.1.3 with 152 commits. Example commit messages:

• Ajax: Always use script injection in globalEval … bbdfbb4
• Effects: Reintroduce use of requestAnimationFrame … 72119e0
• Effects: Improve raf logic … 708764f
• Build: Move test to appropriate module fbdbb6f
• Build: Update commitplease dev dependency
• ...

GitHub and Git

Git is a distributed version control system created by Linus Torvalds for Linux kernel development. It has since become widely adopted in other projects, especially in the Ruby community.

GitHub hosts Git repositories and provides a web interface. Its unique feature is the ease of forking projects. Contributing is simple: fork the project, make changes, and submit a pull request. GitHub has been called the MySpace for coders.

Creating a Project on GitHub

Let’s create a project:

You’ll see the following prompt:

It provides multiple ways to create a repository:

…or create a new repository on the command line

echo "# github-roam" >> README.md
git init
git add README.md
git commit -m "first commit"
git remote add origin git@github.com:phodal/github-roam.git
git push -u origin master

…or push an existing repository from the command line

git remote add origin git@github.com:phodal/github-roam.git
git push -u origin master

Once done, you might wonder what kind of project to build.

GitHub Popular Project Analysis

I’ve previously analyzed GitHub user behavior. Let’s talk about GitHub Stars (as of March 9, 2015, 23:00).

User	Project	Language	Star	URL
twbs	Bootstrap	CSS	78490	https://github.com/twbs/bootstrap
vhf	free-programming books	-	37240	https://github.com/vhf/free-programming-books
angular	angular.js	JavaScript	36,061	https://github.com/angular/angular.js
mbostock	d3	JavaScript	35,257	https://github.com/mbostock/d3
joyent	node	JavaScript	35,077	https://github.com/joyent/node

These are the top 5 projects. Among projects with over 10,000 Stars (82 in total), the distribution is as follows:

Language	Number of Projects
JavaScript	37
Ruby	6
CSS	6
Python	4
HTML	3
C++	3
VimL	2
Shell	2
Go	2
C	2

Category distribution:

• Libraries and frameworks: e.g., jQuery.
• Systems: e.g., Linux, hhvm, docker.
• Configuration sets: e.g., dotfiles.
• Auxiliary tools: e.g., oh-my-zsh.
• Tools: e.g., Homebrew and Bower.
• Resource collections: e.g., free programming books, You-Dont-Know-JS, Font-Awesome.
• Others: e.g., resumes like Resume.

Pull Request

Besides creating projects, we can also contribute via Pull Requests.

My First PR

My first PR was for a small Node.js CoAP-related library. The reason was simple: its README.md had an error that prevented me from proceeding.

const dgram = require('dgram')
-    , coapPacket = require('coap-packet')
+    , package = require('coap-packet')

Simple but useful. Another example:

else
  cat << END
$0: error: module ngx_pagespeed requires the pagespeed optimization library.
-Look in obj/autoconf.err for more details.
+Look in objs/autoconf.err for more details.
END
  exit 1
fi

CLA

CLA stands for Contributor License Agreement. When submitting Pull Requests to large organizations, you may need to sign this agreement. They’ll ask you to register on their website and agree to the terms before accepting your PR.

Here’s a PR I submitted to Google:

And one to Eclipse:

Both required me to sign a CLA.

Building GitHub Projects

How to Use GitHub Effectively

Using GitHub effectively and practicing agile software development is interesting. We can do many things on GitHub, from testing to CI to automated deployment.

Agile Software Development

I’m obviously joking—this has little to do with agile software development. But I don’t know much about waterfall development either. Here’s what I know about project composition:

• Kanban-style application management (like Trello).
• CI (Continuous Integration).
• Test coverage.
• Code quality (code smell).

For a non-remote team (e.g., a one-person project), Trello, Jenkins, and Jira aren’t necessary:

You exist, deeply in my mind.

When you’re alone, you just need to know what you want. What we need are CI and testing to improve code quality.

Testing

Usually, we look for documentation. If there isn’t any, what do you do? Look at the source code or the tests?

it("specifying response when you need it", function (done) {
    var doneFn = jasmine.createSpy("success");

    lettuce.get('/some/cool/url', function (result) {
        expect(result).toEqual("awesome response");
        done();
    });

    expect(jasmine.Ajax.requests.mostRecent().url).toBe('/some/cool/url');
    expect(doneFn).not.toHaveBeenCalled();

    jasmine.Ajax.requests.mostRecent().respondWith({
        "status": 200,
        "contentType": 'text/plain',
        "responseText": 'awesome response'
    });
});

Source: https://github.com/phodal/lettuce

The test case above clearly explains the usage, even if it’s a bit rough.

Wait, what is testing for? Let’s talk about why I wanted to write tests:

• I don’t want to manually test each feature every time I finish a new one (automated testing).
• I don’t want to refactor and accidentally break existing functionality without realizing it.
• I’m afraid to push code because I’m not confident.

Although I’m not a die-hard TDD fan, the purpose of testing is to ensure functionality works. TDD doesn’t necessarily help us write higher-quality code, but sometimes it’s useful for writing simpler logic.

Maybe you already know frameworks like Selenium, Jasmine, Cucumber, etc., and have seen tests like:

 Ajax
   ✓ specifying response when you need it
   ✓ specifying html when you need it
   ✓ should be post to some where
 Class
   ✓ respects instanceof
   ✓ inherits methods (also super)
   ✓ extend methods
 Effect
   ✓ should be able fadein elements
   ✓ should be able fadeout elements

Source: https://github.com/phodal/lettuce

Each test seems small, but after completing all tests, we get test coverage:

File	Statements	Branches	Functions	Lines
lettuce.js	98.58% (209 / 212)	82.98% (78 / 94)	100.00% (54 / 54)	98.58% (209 / 212)

After local tests pass, we add Travis-CI to run our tests.

CI

Although Node.js isn’t strictly a language, since we’re using Node, here’s a simple .travis.yml example:

language: node_js
node_js:
    - "0.10"

notifications:
    email: false

before_install: npm install -g grunt-cli
install: npm install
after_success: CODECLIMATE_REPO_TOKEN=321480822fc37deb0de70a11931b4cb6a2a3cc411680e8f4569936ac8ffbb0ab codeclimate < coverage/lcov.info

Source: https://github.com/phodal/lettuce

After integrating this into README.md, we get the earlier diagram.

CI is crucial for developers working on the same project from different locations, as it ensures project robustness when new features are added with test coverage.

Code Quality

Tools like jslint only ensure syntax correctness but don’t guarantee you won’t write code with bad smells, such as:

• Duplicate code.
• Overly long functions.
• Etc.

Code Climate is a tool integrated with GitHub that provides insights into test coverage and code quality.

Let’s look at the earlier Ajax class:

Lettuce.get = function (url, callback) {
    Lettuce.send(url, 'GET', callback);
};

Lettuce.send = function (url, method, callback, data) {
    data = data || null;
    var request = new XMLHttpRequest();
    if (callback instanceof Function) {
        request.onreadystatechange = function () {
            if (request.readyState === 4 && (request.status === 200 || request.status === 0)) {
                callback(request.responseText);
            }
        };
    }
    request.open(method, url, true);
    if (data instanceof Object) {
        data = JSON.stringify(data);
        request.setRequestHeader('Content-Type', 'application/json');
    }
    request.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
    request.send(data);
};

Source: https://github.com/phodal/lettuce

Code Climate highlights several issues:

• Missing "use strict" statement. (Line 2)
• Missing "use strict" statement. (Line 14)
• 'Lettuce' is not defined. (Line 5)

These are minor issues, but sometimes you might see:

• Similar code found in two :expression_statement nodes (mass = 86)

This indicates duplicate code that can be refactored.

Module Separation and Testing

Earlier, I mentioned:

After nearly half a month of hard work—understanding, refactoring, upgrading versions, adjusting, adding features, adding tests, adding CI, and sharing—the project is almost finished.

Today, let’s discuss how to achieve this.

Take Lettuce as an example. It includes:

• Code quality (Code Climate).
• CI status (Travis CI).
• Test coverage (96%).
• Automated testing (npm test).
• Documentation.

According to the Web Developer Roadmap, we also need:

• Version management.
• Automated deployment.

And more.

Code Modularization

The SkillTree source code is divided into three parts:

• Namespace functions.
• Calculator (TalentTree), responsible for parsing, generating URLs, avatars, dependencies, etc.
• Skill, mainly tips.

All of this was in a single JS file, which is fine for a library but not ideal for a project.

Dependencies include:

• jQuery.
• Knockout.

Fortunately, Knockout can be managed with Require.js, so we used Require.js:

<script type="text/javascript" data-main="app/scripts/main.js" src="app/lib/require.js"></script>

The main.js configuration:

require.config({
  baseUrl: 'app',
  paths:{
    jquery: 'lib/jquery',
    json: 'lib/json',
    text: 'lib/text'
  }
});

require(['scripts/ko-bindings']);

require(['lib/knockout', 'scripts/TalentTree', 'json!data/web.json'], function(ko, TalentTree, TalentData) {
  'use strict';
  var vm = new TalentTree(TalentData);
  ko.applyBindings(vm);
});

The text and JSON plugins handle web.json, which uses JSON to define skills. Different classes are now in separate JS files.

.
|____Book.js
|____Doc.js
|____ko-bindings.js
|____Link.js
|____main.js
|____Skill.js
|____TalentTree.js
|____Utils.js

Later, recommended reading books and links were added. Book and Link inherit from Doc.

define(['scripts/Doc'], function(Doc) {
  'use strict';
  function Book(_e) {
    Doc.apply(this, arguments);
  }
  Book.prototype = new Doc();

  return Book;
});

This was refactored later. The Doc class is a simplified version of classes in Skillock:

define([], function() {
  'use strict';
  

Footnotes

1. jQuery is a fast, small, and feature-rich JavaScript library. ↩ ↩²

2. https://en.wikipedia.org/wiki/Richard_Stallman ↩

3. https://www.gnu.org/philosophy/open-source-misses-the-point.html ↩

4. https://en.wikipedia.org/wiki/WTFPL ↩