Merge pull request #459 from Pelican-Elegant/next

Next

.github/pull_request_template.md

@@ -9,6 +9,7 @@
 ## Prerequisites
 
 - [ ] My Pull Request is filled against the `next` branch
+- [ ] All commits in my Pull Request conform to [Elegant Git commit Guidelines](https://elegant.oncrashreboot.com/git-commit-guidelines)
 
 ## Recommended Steps
 

.yaspeller.json

@@ -44,9 +44,12 @@
     "Carr",
     "Carr's",
     "cd",
+    "changelog",
     "ci",
+    "codebase",
     "CodeHilite",
     "codehilite",
+    "commitizen",
     "committer",
     "config",
     "crafted",
@@ -168,6 +171,7 @@
     "README",
     "rebase",
     "rebasing",
+    "refactor",
     "reST",
     "reStructuredText",
     "resubmitting",
@@ -213,6 +217,7 @@
     "w3c_validator",
     "webmasters",
     "Wegner",
+    "whitespace",
     "xiang",
     "xiaoweiz",
     "Xin",

documentation/content/Contributing/automated-release.md

@@ -0,0 +1,42 @@
+---
+Title: Fully automated version management and publishing
+Date: 2019-07-20 23:17
+Slug: fully-automated-version-management-and-publishing
+Category: Contributing
+Authors: Talha Mansoor
+---
+
+Elegant follows "release early, release often" software development philosophy. In this regard, our release process is fully automated.
+
+We use [semantic-release](https://github.com/semantic-release/semantic-release) for version management and publishing.
+
+Our semantic release configuration can be viewed [here](https://github.com/Pelican-Elegant/elegant/blob/master/.releaserc.json).
+
+## CHANGELOG
+
+It generates the change log automatically, therefore you do not have to update the [CHANGELOG](https://github.com/Pelican-Elegant/elegant/blob/master/CHANGELOG.md).
+
+## New Releases and Version Number
+
+semantic-release uses the commit messages to determine the type of changes in the codebase. Following [formalized conventions for commit messages]({filename}./git-commit-guidelines.md), semantic-release automatically determines the next semantic version number, generates a changelog and publishes the release.
+
+Here is an example of the release type that will be done based on a commit messages:
+
+<!-- yaspeller ignore:start -->
+
+| Commit Message                                                                                                                                                                             | Release Type           |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
+| fix(pencil): stop graphite breaking when too much pressure applied                                                                                                                         | Patch Release          |
+| feat(pencil): add 'graphiteWidth' option                                                                                                                                                   | Minor Feature Release  |
+| perf(pencil): remove graphiteWidth option<br><br>BREAKING CHANGE: The graphiteWidth option has been removed.<br>The default graphite width of 10mm is always used for performance reasons. | Major Breaking Release |
+
+<!-- yaspeller ignore:end -->
+
+## Test Release Process Locally
+
+To test semantic-release locally,
+
+1. Install yarn
+1. Run `yarn semantic-release`
+
+It will run the all the checks and steps in dry run mode.

documentation/content/Contributing/commitizen.md

@@ -0,0 +1,50 @@
+---
+Title: Use Commitizen for Git commits
+Subtitle: Recommended
+Date: 2019-07-22 14:15
+Slug: use-commitizen-for-git-commits
+Category: Contributing
+Authors: Talha Mansoor
+---
+
+When you commit with [Commitizen](https://github.com/commitizen/cz-cli), you'll be prompted to fill out any required commit fields at commit time.
+
+## Prerequisites
+
+### Step 1: Install NodeJS and Yarn
+
+Install [Node.js](https://nodejs.org/en/download/) and [Yarn](https://yarnpkg.com/en/docs/install) on your system.
+
+If you are on Windows then try installing them with [scoop.sh](https://scoop.sh/). It saves time and makes update easier.
+
+### Step 2: Install gulp
+
+Run this command from your command line terminal.
+
+```bash
+yarn global add commitizen
+```
+
+## Use Commitizen
+
+We have already gone through the trouble of making Elegant repository [Commitizen friendly](https://github.com/commitizen/cz-cli#making-your-repo-commitizen-friendly).
+
+All you have to do is to stage your changes and then run
+
+```bash
+git-cz
+```
+
+It will prompt you for questions. Just answer them. Commitizen will automatically format it to conform to [Elegant Git commit guidelines]({filename}./git-commit-guidelines.md).
+
+If your Git commit fails for some reasons, like due to [Git hooks]({filename}./pre-commit.md), then you can fix the issue and rerun Commitizen using,
+
+```bash
+git cz --retry
+```
+
+When you use `--retry`, Commitizen does not prompt for answers and reuse the answers that you last submitted.
+
+## Video Demonstration
+
+<script id="asciicast-258540" src="https://asciinema.org/a/258540.js" async></script>

documentation/content/Contributing/git-commit-guidelines.md

@@ -0,0 +1,190 @@
+---
+Title: Git Commit Guidelines
+Subtitle: Mandatory
+Date: 2019-07-20 23:17
+Slug: git-commit-guidelines
+Category: Contributing
+Authors: Talha Mansoor
+---
+
+[TOC]
+
+Elegant release process is [fully automated]({filename}./automated-release.md). It only works if all commit messages adhere to the set rules.
+
+Why?
+
+> semantic-release uses the commit messages to determine the type of changes in the codebase. Following formalized conventions for commit messages, semantic-release automatically determines the next semantic version number, generates a changelog and publishes the release.
+
+Basically, semantic-release goes through the commit messages, parses them and on its bases makes the decisions of publishing new release and new version number.
+
+What are those rules?
+
+Elegant development team chose to use [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines).
+
+Following portion is largely derived from their [guidelines](https://gist.github.com/stephenparish/9941e89d80e2bc58a153).
+
+!!! Tip "Use Commitizen"
+
+    Reading, understanding and then getting used to following guidelines may take sometime.
+
+    Make your life easier and [use Commitizen for Git commits]({filename}./commitizen.md).
+    It automatically formats the commit message to conform to our guidelines.
+
+## Commit Message Format
+
+Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
+format that includes a **type**, a **scope** and a **subject**:
+
+```text
+<type>(<scope>): <subject>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+The **header** is mandatory and the **scope** of the header is optional.
+
+Any line of the commit message cannot be longer 100 characters! This allows the message to be easier
+to read on GitHub as well as in various git tools.
+
+## Header
+
+### Revert Commits
+
+If the commit reverts a previous commit, it should begin with `revert:`, followed by the header
+of the reverted commit.
+In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit
+being reverted.
+
+### Type
+
+Must be one of the following:
+
+- **feat**: A new feature
+- **fix**: A bug fix
+- **docs**: Documentation only changes
+- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
+  semi-colons, etc)
+- **refactor**: A code change that neither fixes a bug nor adds a feature
+- **perf**: A code change that improves performance <!-- yaspeller ignore -->
+- **test**: Adding missing or correcting existing tests
+- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
+  generation
+
+### Scope
+
+The scope could be anything specifying place of the commit change. For example, `authors` if the change is about Elegant [authors blurb]({filename}../Supported Plugins/author-blurbs.md) feature or `home` if it refers to [landing page]({filename}../Landing Page/landing-page.md).
+
+## Subject Text
+
+1.  use imperative, present tense: "change" not "changed" nor "changes" not "changing"
+1.  don't capitalize first letter
+1.  no dot (.) at the end
+
+### What is Imperative mode
+
+[Here](https://chris.beams.io/posts/git-commit/#imperative) is a very good explanation of imperative mode.
+
+> Imperative mood just means "spoken or written as if giving a command or instruction". A few examples:
+>
+> 1.  Clean your room
+> 1.  Close the door
+> 1.  Take out the trash
+>
+> The imperative can sound a little rude; that's why we don't often use it. But it's perfect for Git commit subject lines.
+
+## Body
+
+1. just as in use imperative, present tense: “change” not “changed” nor “changes”
+1. includes motivation for the change and contrasts with previous behavior
+
+## Footer
+
+### Breaking changes
+
+All breaking changes have to be mentioned in footer with the description of the change, justification and migration notes.
+
+Example,
+
+```text
+feat(home): write about me in markdown, reST or asciidoc
+
+BREAKING CHANGE: Previously LANDING_PAGE_ABOUT was a dictionary that contained html tags. We used it
+to create landing page. But users have demanded from the very beginning to be able to write the
+landing page in markdown. This patch adds this feature. But in order to use it, you have to update
+your configuration.
+
+Closes #85
+```
+
+### Referencing issues
+
+Closed bugs should be listed on a separate line in the footer prefixed with "Closes" keyword like this:
+
+```text
+Closes #234
+```
+
+or in case of multiple issues:
+
+```text
+Closes #123, #245, #992
+```
+
+In case your commit affects an issue, use "Updates" keyword
+
+```text
+Updates #234
+```
+
+## Examples
+
+Following are few example commits that shows how Elegant has uses these guidelines.
+
+### New Features
+
+```text
+feat(monetization): add BestAzon support
+feat(Chinese): add better font support for Chinese language
+feat(footer): make external links Nofollow
+```
+
+### Fixes
+
+```text
+fix(reST): indents in line blocks is not preserved
+fix(gist): embedded Github gist are not laid out correctly
+```
+
+### Documentation
+
+```text
+docs(add): metadata variables
+docs(add): release notes for 3.0.0
+docs(update): change category of reading-time article
+docs(update): set author information
+```
+
+### Miscellaneous
+
+```text
+chore(livereload): use es2015 syntax for gulp configuration
+ci(docs): use sitemap plugin in production only
+ci(docs): add default tasks.py file
+refactor: move Google and Bing claims to their individual files
+```
+
+## Examples of Incorrect Commit Messages
+
+This commit message starts with a capital letter and ends with a period
+
+```text
+doc(changes): Rewrite of multi-part plugin per issue 308.
+```
+
+This commit message does not use imperative mode.
+
+```text
+docs(change): updating status doc to reflect current state
+```

documentation/content/Contributing/pre-commit.md

@@ -0,0 +1,43 @@
+---
+Title: Use Pre-Commit Git Hooks
+Date: 2019-07-22 23:17
+Slug: use-pre-commit-git-hooks
+Category: Contributing
+Authors: Talha Mansoor
+---
+
+Since Elegant has moved to [bazar development model]({filename}./community-driven-project.md), we want to make sure all patches follow the same stylistic guidelines.
+
+We leverage Git hooks to auto format all the patches. But Git hooks are hard to manage and sync. Therefore we decided to use [Pre-Commit](https://pre-commit.com/) which provides an abstraction over the Git hooks.
+
+Pre-commit makes managing, sharing and updating the Git hooks very easy. You can set it up once and then forget about it.
+
+To install pre-commit,
+
+```bash
+pip install pre-commit
+```
+
+Then in the root of your Elegant repository run,
+
+```bash
+pre-commit install
+```
+
+That's it. You don't have to worry about it anymore.
+
+Next time when you will try to do a Git commit, pre-commit will download all the tools required for running the Git hooks. It may take sometime but this is a one time operation. Once tools are in the place, Git hooks will run before every Git commit.
+
+In almost all cases, you will not have to do anything. It will run the hooks, format the files and notify you of error. You will then stage the changed files and retry your commit.
+
+## Why use pre-commit at all?
+
+Pre-commit runs Git hooks that among other things,
+
+1. Run [Prettier](https://github.com/prettier/prettier) on Markdown, CSS, JS and json files
+1. Run [Black](https://github.com/python/black) on Python files
+1. Removes trailing whitespace
+
+## Pull Requests and pre-commit
+
+We have setup pre-commit to run on all pull requests using Travis CI. Travis runs pre-commit and on error, reports build failure.

documentation/pelicanconf.py

@@ -28,15 +28,16 @@
 
 PLUGIN_PATHS = ["plugins"]
 PLUGINS = [
+    "assets",
     "extract_toc",
-    "tipue_search",
+    "just_table",
     "liquid_tags.img",
     "neighbors",
-    "render_math",
     "related_posts",
-    "assets",
-    "share_post",
+    "render_math",
     "series",
+    "share_post",
+    "tipue_search",
 ]
 SITEMAP = {
     "format": "xml",

documentation/tasks.py

@@ -119,7 +119,7 @@ def plugins_sync(c):
     # --recurse-submodules and --shallow-submodules switches
     # Do specify path in --recurse-submodules so that only relevant plugin is downloaded
     c.run(
-        "git clone --jobs 8 --depth 1 https://github.com/getpelican/pelican-plugins.git plugins"
+        "git clone --jobs 8 --depth 1 --recurse-submodules=just_table --shallow-submodules  https://github.com/getpelican/pelican-plugins.git plugins"
     )