dan
/
jekyll
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update philosophy document based on benbalter's feedback.

This commit is contained in:
Parker Moore 2017-03-27 13:03:42 -04:00
parent 2c19264d08
commit f2bf984160
No known key found for this signature in database
GPG Key ID: 193CDEBA72063C58
1 changed files with 12 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/philosophy.md
View File

@ -11,7 +11,8 @@ is about, the following principles should come to mind:
Jekyll is not magic. A user should be able to understand the underlying Jekyll is not magic. A user should be able to understand the underlying
processes that make up the Jekyll build without much reading. It should processes that make up the Jekyll build without much reading. It should
behave "as you'd expect." do only what you ask it to and nothing more. When a user takes a certain
action, the outcome should be easily understandable and focused.
### 2. It "Just Works" ### 2. It "Just Works"
@ -19,7 +20,7 @@ The out-of-the-box experience should be that it "just works." Run `gem
install jekyll` and it should build any Jekyll site that it's given. install jekyll` and it should build any Jekyll site that it's given.
Features like auto-regeneration and settings like the markdown renderer Features like auto-regeneration and settings like the markdown renderer
should represent sane defaults that work perfectly for the vast majority of should represent sane defaults that work perfectly for the vast majority of
cases. The burden of configuration should not be placed on the user. cases. The burden of initial configuration should not be placed on the user.
### 3. Content is King ### 3. Content is King
@ -31,6 +32,12 @@ should find the management of their content enjoyable and simple.
If a user's site builds today, it should build tomorrow. If a user's site builds today, it should build tomorrow.
Backwards-compatibility should be strongly preferred over breaking changes. Backwards-compatibility should be strongly preferred over breaking changes.
Breaking changes should be made to support a strong practical goal, and
breaking changes should never be made to drive forward "purity" of the
codebase, or other changes purely to make the maintainers' lives easier.
Breaking changes provide a significant amount of friction between upgrades
and reduce the confidence of users in this software, and should thus be
avoided unless absolutely necessary.
Upon breaking changes, provide a clear path for users to upgrade. Upon breaking changes, provide a clear path for users to upgrade.
### 5. Small & Extensible ### 5. Small & Extensible
@ -38,4 +45,6 @@ Upon breaking changes, provide a clear path for users to upgrade.
The core of Jekyll should be simple and small, and extensibility should be The core of Jekyll should be simple and small, and extensibility should be
a first-class feature to provide added functionality from community a first-class feature to provide added functionality from community
contributors. The core should be kept to features used by at least 90% of contributors. The core should be kept to features used by at least 90% of
users–everything else should be provided as a plugin. users–everything else should be provided as a plugin. New features should
be shipped as plugins and focus should be put on creating extensible core
API's to support rich plugins.