Skip to content

Latest commit

 

History

History
162 lines (104 loc) · 6.73 KB

guide-for-contributor.md

File metadata and controls

162 lines (104 loc) · 6.73 KB
Raw

Guide for Contributor

Screenshot on MAC

By default, we prefer taking screenshot of proper sized window. Please check out "How to take a screenshot of a window" of this post.

Heading levels

  • # -- The main title of this page. It will show as <h1> in rendered format, or in the <title> of an HTML page's meta sections.
  • ## -- The first level of section heading.
  • ### -- The second level of section heading.

Git commit message

Write a brief commit message so others can quickly comprehend the changes in this commit. If the commit message is complex, write a brief line within 70 characters and the remaining texts in the body after line break.

Bad example:

Bad example of Git commit message

Good example:

Good example of Git commit message

File naming convention

Adopt the URL-slug convention:

  • All lowercase. Exception can be made when part of the phrase is an acronym.
  • Replace blanks by dash, i.e. -.
  • Put informative phrases into the path, so that the content/ meaning of the file can be quickly comprehended from its path/ URL.
  • Only use alphabets, numbers, dash and dot (for extension name).

The way to check if a file path is URL-friendly or not is straightforward. Just copy and paste this path into your browser's address bar and see if it is changed to another string. For example, a single blank will be changed to %20 in the address bar. If it stays the same, we think it is URL-friendly.

Good example:

git-commit-message-good.png

Bad example 1: (blanks are not URL friendly)

git commit Message Good.png

Bad example 2: (not informative enough; may clash with other screenshots)

git.png

Bad example 3: (not informative enough; may clash with other screenshots)

commit.png

Table of Contents (TOC)

In VSCode, install the following plugin and follow the menu to generate TOC for a markdown document.

markdown TOC plugin screenshot

The TOC generated by this plugin (Markdown TOC by AlanWalk) is automatically updated. Please do not touch the content in between

<!-- TOC -->
... some listing here
<!-- TOC -->

To help our future development, e.g. render the openbook via a static site generator, please wrap the TOC by another layer of <div id="toc">. The whole TOC code block looks like this:

<div id="toc">
<!-- TOC -->
... some listing here
<!-- TOC -->
</div>

Potential issues:

  • Latest VSCode clashes with the plugin. Checkout this issue for solution. Changing file.eol in the settings can temporarily solve the issue. Use cmd+, to open settings, search file.eol and change to \n on MAC.

Link whenever possible

The beauty of Internet and one of its original design goal is to connect everything. URL/ URI provides a system for inter linking between documents. In our openbook, contributors try the best to link to relevant resources if those resources are public already. When making quote or taking screenshots, it is a convention to link to the original article/ interface.

For example, when explaining how the discussion forum works on GitHub, one do not only have screenshots but also can experience the live version. This Git diff demonstrates how and here is the rendered version.

Link to GitHub comments

Click the date and get a full URL including the URI fragment. Read more on Stack Overflow.

Link to resources in this repo

Use relative links so that moving/ renaming this repo does not break the links. One is example is the README.md file.

Link to other repos

Other repos are usually out of your control. The GitHub web page by default show you the latest content. However, "the latest" will be changed later. To ensure future readers can see exactly what you see, you can use PermaLink to GitHub, i.e. a link that includes a commit hash (see more on notes-week-00.md), which will be resolved to exactly the same version no matter when the future visitors come. You can press y so the URL in the browser address bar is changed to PermaLink. See official explanation.

Editing environment

We suggest to use VSCode with the following extensions:

  • Markdown Preview Enhanced -- See how it works here
  • markdownlint -- See how it works here
  • Markdown TOC by AlanWalk -- See more instructions in the current document, this section

Coding style

It is hard to exhaust coding style issues. We collect some sample discussions here and conclude later if necessary:

Generating GitBook

Related repos:

# gitbook installation
npm install gitbook-cli -g

# gitbook-pdf installation
git clone git@github.com:GitbookIO/gitbook-pdf.git
cd gitbook-pdf
npm i -S phantomjs@2.1
npm link

# PDF export dependencies
npm install svgexport -g
brew search calibre

gitbook pdf .