Merge pull request #19 from ForEvolve/add-docs-about-toggling

Update docs
ForEvolve · Oct 7, 2019 · c82a54d · c82a54d
2 parents 8b2744e + 4fdbfa0
commit c82a54d
Show file tree

Hide file tree

Showing 2 changed files with 67 additions and 13 deletions.
diff --git a/package.json b/package.json
@@ -21,6 +21,13 @@
     "dark-theme"
   ],
   "author": "Carl-Hugo Marcotte",
+  "contributors": [
+    { 
+      "name" : "Maciej Krüger", 
+      "email" : "mkg20001@gmail.com", 
+      "url" : "https://mkg20001.io"
+    }
+  ],
   "license": "MIT",
   "dependencies": {
     "bootstrap": "^4.3.1",

diff --git a/readme.md b/readme.md
@@ -1,26 +1,48 @@
 # Bootstrap 4 Dark theme
 
-This is a Bootstrap 4 dark theme.
+Bootstrap 4.3.1 dark theme that supports togging dark/light themes as well. There is no fluff, it changes the color of Bootstrap and that's it, no new thing to learn or unlearn, just Bootstrap, but Dark!
 
 ![VSTS build badge](https://forevolve.visualstudio.com/_apis/public/build/definitions/c685c54e-c04f-4c62-9e82-db39a452f4d9/22/badge)
 
 ## Alpha - preview
 
-_This is a work in progress..._
-
 ![Alpha - preview](assets/images/alpha-3.png)
 
+_This is a work in progress, if you like it and have some spare time, contributions are welcome._
+
+## Versioning
+
+SemVer is used to keep things easy for everyone.
+
+### Prerelease
+
+Until the project reaches an official version `1.0.0`, the pre-release `-alpha.[build number]` suffix is added to the version number.
+
+Since this is only a dark version of Bootstrap, there should not be many breaking changes worth investing in versioning. So don't worry too much about compatibility, updating to the latest `alpha` release should be safe enough.
+
+If this is a major concerns to you, feel free to say so, and I'll see what I can do about it.
+
 ## How to use
 
-Official builds are available in the public npm repository.
+Official builds are available in the public npm registry.
 
 ```
 npm install @forevolve/bootstrap-dark --save
 ```
 
-The CI builds are deployed to the following custom npm registry: <https://www.myget.org/F/forevolve/npm/>.
+The package contains the content of the `dist` directory which includes the Bootstrap JavaScript files, for convenience, and the Bootstrap Dark CSS files.
+To load the dark theme, `<link>` the `bootstrap-dark.css` or the `bootstrap-dark.min.css` instead of the `bootstrap[.min].css` file.
+
+### Dark/Light toggle
+
+You can now `<link>` both the `toggle-bootstrap.css` and the `toggle-bootstrap-dark.css` files to allow toggling the normal/dark theme based on your page body.
+
+-   To display the original Bootstrap color, apply the `bootstrap` class on your body, like `<body class="bootstrap">`.
+-   To display the Bootstrap Dark theme, apply the `bootstrap-dark` class on your body, like `<body class="bootstrap-dark">`.
 
-> TODO: write a better guide...
+### CI builds
+
+The CI builds are deployed to the following custom npm registry: <https://www.myget.org/F/forevolve/npm/>.
 
 ## How to build
 
@@ -63,24 +85,49 @@ There is a few npm and gulp scripts.
 1. `watch` execute `copy-bootstrap-js` then watch to rebuild the theme.
 1. `default` simply runs both `build-theme` and `copy-bootstrap-js`.
 
-### Contribute
-
-To contribute, feel free to contact me.
-
-If you feel confident enough (or if the issue tracker is more populated and I forgot to update this section), feel free to submit a PR.
-
 ## The project structure
 
 -   `app` is the Asp.Net Core application that is used to test the theme. This directory is not packaged.
     -   `Pages` are the Asp.Net Core Razor Pages. That's the preview.
-        > **Why .NET Core?** Well, I wanted to script some loops, and I know .Net; so I picked Razor Pages to do just that: dynamic pages!
+        > **Why .NET Core?** Well, I wanted to script some loops, and I know .Net; so I picked Razor Pages to do just that: dynamic pages! Moreover, it is open source and cross-platform.
+        >
+        > If you think that something else would be better, feel free to open an issue about it; I would not mind switching to another technology (see the Contribute section below).
     -   `Services` are the web pages services; so far it's pretty thin.
     -   `wwwroot` are the web assets; the `dist` files are copied there.
 -   `assets` are the project assets (like the screenshot in the readme file).
 -   `dist` are the redistributable files; if you want to copy/paste the files into your projects, that's the ones. They also include bootstrap JavaScript files, unaltered.
 -   `scss` are the source theme files.
 -   Other files (root): npm, license, readme, etc.
 
+## Contribute
+
+To contribute, start by opening an issue or reply on an existing issue so we can discuss your feature or bug to find the best way to approach it.
+
+Once we settled on a strategy, you can then Fork/Code/Open a PR.
+
+-   Please add yourself in the `package.json` `contributors` array.
+-   Please keep PR focused on a single feature, it is easier for everyone this way and it helps keep the conversation focused. I way prefer multiple smaller PR than a single huge one.
+
+Thanks in advance for your contribution.
+
+See [Contributing to ForEvolve open source projects](https://github.com/ForEvolve/Toc/blob/master/CONTRIBUTING.md) and [Contributor Covenant Code of Conduct](https://github.com/ForEvolve/Toc/blob/master/CODE_OF_CONDUCT.md) for more information.
+
+## Release notes
+
+Since CI build numbers are automated, it is hard to know for sure what the next deployed build number will be, so the `(latest)` version represent that version.
+
+### (latest)
+
+-   Update the project description, the "How to use" section, and add the "Release notes" section
+
+### 1.0.0-alpha.842
+
+-   Add support for dark/light toggling
+
+### 1.0.0-alpha.774 & 1.0.0-alpha.723
+
+-   Initial dark theme
+
 ## References
 
 -   [Bootstrap](https://github.com/twbs/bootstrap/)