From f2bf9841608b631376b7cc699198589eb743a5ce Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Mon, 27 Mar 2017 13:03:42 -0400 Subject: [PATCH] Update philosophy document based on benbalter's feedback. --- docs/philosophy.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/philosophy.md b/docs/philosophy.md index ad9cbb4f..b058183e 100644 --- a/docs/philosophy.md +++ b/docs/philosophy.md @@ -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 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" @@ -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. Features like auto-regeneration and settings like the markdown renderer 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 @@ -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. 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. ### 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 a first-class feature to provide added functionality from community 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.