Add README.txt file to Stable explain its role as a backwards compatibility layer

@davidhernandez
Added few lines to the file. Kindly see if its fine.

Recreated the patch.

@davidhernandez
I have added Heading in accordance with other themes README files, to maintain similar format. As in Stark theme ReadMe file, there are heading in Caps, so it keeps Uniformity.

Changing status

I have compared the file with other Readme files and it is in proper format.

Thanks! I've added a new Stable component to the issue queue.

And this is fairly good, but it really could use some improvement before we add it to Core:

1. +++ b/core/themes/stable/README.txt
   @@ -0,0 +1,29 @@
   +
   +
   +Stable is a base theme with minimal markup and very few classes, and functions
   

   Nitpick: Extra blank line here.

2. +++ b/core/themes/stable/README.txt
   @@ -0,0 +1,29 @@
   +Stable is a base theme with minimal markup and very few classes, and functions
   +as a backwards compatibility layer for Drupal 8's core markup, CSS and JS. This
   

   This first sentence is run/on and/or garbled.

3. +++ b/core/themes/stable/README.txt
   @@ -0,0 +1,29 @@
   +A theme will use Stable as the base theme if no base theme is set in its
   +.info.yml file, or set the base theme setting to false.
   

   The grammar here is garbled.

4. +++ b/core/themes/stable/README.txt
   @@ -0,0 +1,29 @@
   +.info.yml file, or set the base theme setting to false.
   

   false => FALSE I think? Hm, maybe not. Someone check this?

5. +++ b/core/themes/stable/README.txt
   @@ -0,0 +1,29 @@
   +
   +base theme: false
   

   This line is an example for the previous paragraph. It should not be separated by a blank line, and the previous line should end in : to make this clear.

For 4 lowercase is correct.

Created patch with changes suggested by jhodgdon.

Interdiff please :) also looks like the patch doesn't apply.

Recreated Patch and added interdiff file.

1. +++ b/core/themes/stable/README.txt
   @@ -17,9 +16,8 @@ Themes that opt out of using Stable will need continuous maintenance as core
   +Stable will be used as the base theme if no base theme is set in current
   

   "in the current" here would read better.

2. +++ b/core/themes/stable/README.txt
   @@ -0,0 +1,27 @@
   +Stable is a base theme with minimal markup and very few classes, it functions
   

   I would consider ending the sentence after "very few classes" and starting a new one.

3. +++ b/core/themes/stable/README.txt
   @@ -0,0 +1,27 @@
   +theme's .info.yml file, or when the base theme setting is set to false:
   +base theme: false
   

   I didn't read this closely enough. Stable will *not* be used when you set base theme to false, that's how you opt out as is discussed in the previous paragraph.

Thanks @anil280988!

Interdiff please!

1. +++ b/core/themes/stable/README.txt
   @@ -0,0 +1,27 @@
   +as a backwards compatibility layer for Drupal 8's core markup, CSS and JS. This
   

   Need comma after CSS in this line.

2. +++ b/core/themes/stable/README.txt
   @@ -0,0 +1,27 @@
   +and styling do not affect themes using Stable.
   

   Should this say "... using Stable as a base theme." ?

3. +++ b/core/themes/stable/README.txt
   @@ -0,0 +1,27 @@
   +Stable will be used as the base theme if no base theme is set in the current
   +theme's .info.yml file, or when the base theme setting is set to false:
   

   I think we should not be talking about "the current theme" here.

   Also in the second line, see Cottser's recent review. I think if you set base theme to false, you do NOT get Stable, right?

Thanks Jhodgdon and davidhernandez for clarification.
Attaching patch for review.

@r_sharma08 both patch and interdiff don't seem quite right, can you try generating those again please?

Re attached the patch and interdiff files. Please review

Thanks for fixing up the patch files, but the previous review comments *still* have not been addressed:

1. +++ b/core/themes/stable/README.txt
   @@ -0,0 +1,27 @@
   +Stable will be used as the base theme if no base theme is set in the current
   

   Can we please NOT use the word "current" here? See previous comments.

2. +++ b/core/themes/stable/README.txt
   @@ -0,0 +1,27 @@
   +theme's .info.yml file, or if the base theme setting is set to false:
   +base theme: false
   

   And this is still wrong.

It seems to be a new person writing the patch each time which is not helping. I'm going to go ahead and make those changes.

Summary of changes:

1. +++ b/core/themes/stable/README.txt
   @@ -0,0 +1,27 @@
   +as a backwards compatibility layer for Drupal 8's core markup, CSS, and JS. This
   +allows markup and styling to evolve throughout the life of Drupal 8, while
   

   Removed JS - Stable doesn't contain any JS. Changed "This" to "Stable".

2. +++ b/core/themes/stable/README.txt
   @@ -0,0 +1,27 @@
   +and styling do not affect themes using Stable as base theme.
   

   as base theme = as a base theme, per #23.2.

3. +++ b/core/themes/stable/README.txt
   @@ -0,0 +1,27 @@
   +Themes that opt out of using Stable will need continuous maintenance as core
   +changes, so only do so if you are prepared to keep track of those changes and
   +how they affect your theme.
   ...
   +Stable will be used as the base theme if no base theme is set in the current
   +theme's .info.yml file, or if the base theme setting is set to false:
   +base theme: false
   

   Updated the opt-in/opt-out details and moved the "Themes that opt out of using Stable" to after where we tell them how to opt out. Made it more of a clear warning. See interdiff/patch for all the details :)

Overall to me the first paragraph reads more like an explanation we would give to a core contributor rather than a new themer (for example). It also contradicts the next paragraph with this phrase: "clean, minimal markup provided by core". I think we can make it easier to understand. Here's an attempt:

Stable is the default base theme in Drupal 8 which provides minimal markup and very few classes. If you prefer more structure and classes see the Classy base theme (also in Drupal core).

All the backwards compatibility, evolution, etc. stuff could be explained further down I think for those who are interested. I also think we should add a similar README to Classy which points back to Stable.

Thoughts?

Bueno.

Excellent. As Cottser is theme system maintainer, and I am docs maintainer, and both of us like this, I went ahead and committed it to both 8.x branches. And I'll take a look at the other issue too for Classy. THANKS!

Well we can still iterate on it (my thoughts about the first paragraph, I will open a new issue for that to not hold this up any more). Thanks @jhodgdon! Glad to see we have a README in now.

#2630592: Tweak Stable's README.txt to be more understandable by new users