[RFC] plugin-git-log

rfcs/002.plugin-git-log.md

@@ -0,0 +1,126 @@
+- Start Date: 2019-03-06
+- RFC PR: (leave this empty)
+- VuePress Issue: (leave this empty)
+
+# Summary
+
+A new official plugin `@vuepress/plugin-git-log` featured with more computed properties to be mixed in.
+
+# Basic example
+
+1. Apply the plugin `@vuepress/git-log`.
+2. It will provide a computed property `$git`, with following attributes:
+   - **$git.updated:** the last updating time for this page
+   - **$git.created:** the first creating time for this page
+   - **$git.author:** the author for this page
+   - **$git.contributors:** contributors for this page
+   - **$git.commits:** detailed informations of commits to this page
+
+# Motivation
+
+Although last-updated works well, git-log provides more information. Such plugin will provide remarkable convenience to users, because it automatically generates some necessary meta information.
+
+# Detailed design
+
+## Computed Properties
+
+We will get all computed properties through a command line like this:
+
+```bash
+git log --format="%h %at %ct %an"
+```
+
+Passing the result to client, we will get a `$git.commits` like this:
+
+```json
+[{
+  "hash": "aabbccd",
+  "authorTime": 11111111,
+  "commitTime": 22222222,
+  "author": "fooooooo"
+}, {
+  "hash": "ffeeddc",
+  "authorTime": 33333333,
+  "commitTime": 44444444,
+  "author": "baaaaaar"
+}]
+```
+
+And other computed properties can be derived from this.
+
+## Options
+
+### formatTime
+
+A function to format unix time. It may have two arguments: `time` and `lang`. The default value will be:
+
+```js
+function formatTime (timestamp, lang) {
+  return new Date(timestamp).toLocaleString(lang)
+}
+```
+
+### additionalProps
+
+Aside from some properties listed above, we can add some custom properties throuth this option:
+
+```js
+module.exports = {
+  plugins: [
+    ['@vuepress/git-log', {
+      additionalProps: {
+        subject: '%s',
+        authorEmail: '%ae',
+      }
+    }]
+  ]
+}
+```
+
+### additionalArgs
+
+A string or an array of strings to include all the additional args. The default value will be `'--no-merge'`.
+
+### onlyFirstAndLastCommit
+
+If set to `true`, this plugin will only look for the first and last commit, which may save lots of time. The default value is `false`.
+
+However, setting this option to also means you will have no access to **\$git.contributors** and **$git.commits**.
+
+# Drawbacks
+
+- It will replace existing plugin `@vuepress/plugin-last-updated`, which may lead to a breaking change (also see [adoption-strategy](#adoption-strategy)).
+- It will cost more time to get all the detailed informations on a large git project than in the past with default options (because `onlyFirstAndLastCommit` is `false`).
+
+# Alternatives
+
+Publish multiple packages like `@vuepress/plugin-last-updated`. But in that case, we may need lots of command lines, which may seriously affect performance.
+
+# Adoption strategy
+
+We will deprecate `@vuepress/plugin-last-updated` after several months. Before then, we will automatically import `@vuepress/plugin-git-log` in `@vuepress/plugin-last-updated` and support both functionality.
+
+```js
+// server
+module.exports = {
+  plugins: ['@vuepress/last-updated']
+  // show deprecation warnging
+}
+```
+```js
+// client
+export default {
+  created () {
+    console.log(this.$lastUpdated) // show deprecation warnging
+    console.log(this.$git.updated)
+  }
+}
+```
+
+# How we teach this
+
+Through official plugin documentation (i.e. `/plugin/official/plugin-git-log.html`).
+
+# Unresolved questions
+
+N/A