From cad6a0f1487da33c44254713b6aa9da90f25550b Mon Sep 17 00:00:00 2001 From: the-j0k3r <31389848+the-j0k3r@users.noreply.github.com> Date: Mon, 20 Jul 2020 10:21:24 +0100 Subject: [PATCH] simplify and rework docs For new contributors unfamiliar with GHD dev process, the absolute minimum info I'de expect to find in any project of this complexity. We got rid of contributors MD, so IMO the additions would have made my life easier in the beggining. ** Theres room for improvement as with all things. Notes: Indtead of adding remap-css short how to into readme I added to header of mappings.js it can be further broken down to make clear what things do. --- CONTRIBUTING.md | 104 -------------------------------------------- README.md | 45 ++++++++++++------- src/gen/mappings.js | 8 ++++ 3 files changed, 38 insertions(+), 119 deletions(-) delete mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index cbd8d2033..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,104 +0,0 @@ -# Contributing to GitHub-Dark - -1. [Getting Involved](#getting-involved) -2. [How To Report style issues](#how-to-report-style-issues) -3. [Core Style Guide](#github-dark-style-guide) -4. [Getting Started](#getting-started) - -## Getting Involved - -There are a number of ways to get involved with the development of this GitHub Dark theme for Stylus. Even if you've never contributed to an Open Source project before, we're always looking for help identifying missing styles or other issues. - -Feel free to help us out in any capacity, StylishThemes is always looking for help with our busy schedule. Open an issue to discuss any related contribution minutia or just to clear up any doubts you may have. - -## How to Report Style issues - -### I don't know CSS -If you don't know CSS very well and have found a missing style, please include as much as possible of the following information when opening an issue: - -* Screenshot of the problem; include the element(s) in the console if at all possible - * To select an element, target it with your mouse then right-click and choose "Inspect Element" - * Please include both the HTML view and the element with the problem in the screenshot (see [issue #119](https://github.com/StylishThemes/GitHub-Dark/issues/119) for an example) -* A URL to the page (if public). - -### I rock at CSS & GitHub! -* Follow the style guide below -* Make any needed changes, then send us a pull request -* Please include a URL to the page (if public) - -## GitHub Dark Style Guide - -* Use the provided `.editorconfig` file with your code editor. Don't know what that is? Then check out http://editorconfig.org/. -* Limit to the [K&R (KNF variation style)](https://en.wikipedia.org/wiki/Indentation_style#Variant:_BSD_KNF), and **2 SPACE INDENTATION** (no tabs, and not more, and not less than 2 spaces). - - * K&R - KNF Variation Example: - ```css - element[attr='value'] { - ··property: value; - } - ``` - - * **Not Allman** - ```css - element[property='value'] - { - ··property: value; - } - ``` - - * Strict space between the `selector` and the `{`: - ```css - /* good */ - element[attr='value'] { } - - /* bad */ - element[attr='value']{ } - ``` - - * 2 Space indentation - ```css - /* good */ - ··property: value; - - /* bad */ - ····property: value; - ----property: value; - ·property: value; - ``` -⚠️ Any new additions should be mapped using the built-in generator before adding any manual rules or selectors, please study the [rules.js](./src/rules.js), if you have any doubts or questions please feel free to open an issue to to start a releated discussion. - -Do not manually edit generated areas, as those additions are lost on running `make build` developemnt script. - -Don't include version bumps with your contribution, all releases are handled internally. - -## Tips - -* Try to wrap lines at around 250 characters. If at all possible, use "make clean" to do the wrapping for you. -* Don't add any image URI's to the CSS; instead add the image into the `/images` directory; then point to using the following URL: `http://stylishthemes.github.io/Github-Dark/images/`{my-image.png}. - * If possible, reduce any added selectors. Remember that Stylus may need an `!important` flag to override default styling, so a selector starting with body isn't always necessary, Use !important only if necessary. - * Do add inline comments for manual additions. - Also add comment as a note in the commit message body. - * If your CSS definition already exists within the style, do not add it again! Add your selector to the existing rule block. -* Insert any new manual CSS selectors in any available slot before the style definition, or on a new line as needed. -* If you want to add a new userstyle variable, please open an issue and discuss it with us first. -* If your PR fixes an open issue or replaces another PR, include fixes/closes #issue-nr in your commit message title. [Read more on this](https://help.github.com/en/articles/closing-issues-using-keywords). - - -## Getting Started - -* [Download](https://github.com/StylishThemes/GitHub-Dark/archive/master.zip), [fork](https://github.com/StylishThemes/GitHub-Dark/fork) or clone this repository. - -First, make sure you have these installed: - -- [`node`](https://nodejs.org): version 12 or greater -- [`yarn`](https://classic.yarnpkg.com/en/docs/install/): version 1 -- `make`: comes with UNIX-like OS, on Windows you can use [this](https://stackoverflow.com/a/54086635/808699) - -### Edit, Build & test - -* **Generator entries**, edit [rules.js](./src/rules.js) -* **Manual entries,** edit files in [src](./src) file to include any customizations to the style. -* Run `make` to build and install the new style. -* Now you can push the changes to your fork and submit a pull request. -* If you haven't already contributed, then also run `make authors` to add your name to our list of contributors :smile: -* And thanks again for contributing! diff --git a/README.md b/README.md index 5d466ab35..50ced2738 100644 --- a/README.md +++ b/README.md @@ -100,30 +100,36 @@ [1]:https://github.com/StylishThemes/GitHub-Dark/pull/568 -## Notes +## Contributions and Development -- If you're using a custom domain for GitHub Enterprise, be sure to include it through a `@-moz-document` rule (Firefox) or add it to the `Applies to` section in (Chrome). +If you would like to contribute to this repository, please... -## Contributions +1. [![fork](https://user-images.githubusercontent.com/136959/42383736-c4cb0db8-80fd-11e8-91ca-12bae108bccc.png) Fork](https://github.com/StylishThemes/GitHub-Dark/fork) +1. Make sure you have these installed: -If you would like to contribute to this repository, please... +- [`node`](https://nodejs.org): version 12 or greater +- [`yarn`](https://classic.yarnpkg.com/en/docs/install/): version 1 +- `make`: available with UNIX-like OS, on Windows you can use [this](https://stackoverflow.com/a/54086635/808699) -1. 👓 Read the [contribution guidelines](./CONTRIBUTING.md). -1. [![fork](https://user-images.githubusercontent.com/136959/42383736-c4cb0db8-80fd-11e8-91ca-12bae108bccc.png) Fork](https://github.com/StylishThemes/GitHub-Dark/fork) or [![cloud-download](https://user-images.githubusercontent.com/136959/42401932-9ee9cae0-813d-11e8-8691-16e29a85d3b9.png) download](https://github.com/StylishThemes/GitHub-Dark/archive/master.zip) this repository. -1. 👌 Create a pull request! +Then run `make deps` to install dependencies. -## Development +### Auto generated CSS -First, make sure you have these installed: +Contributing e.g unstyled items, sources, extensions, etc. to name a few. -- [`node`](https://nodejs.org): version 12 or greater -- [`yarn`](https://classic.yarnpkg.com/en/docs/install/): version 1 -- A Unix-like environment with `make` (on Windows use [this](https://stackoverflow.com/a/54086635/808699)) +See and edit the respective files in [/src/gen/](./src/gen/). + +And then run `make build install` to rebuild the style and install it test you fixes and PR back. + +### Manual override entries -Edit the files in [`src`](./src) and then run `make build install` to rebuild the style and install it. +Manual overrides to e.g. generated content or inline HTML styles to name a few; + +See and edit respective files in [`src`](./src) and then run `make build install` to rebuild and install the style, to test you fixes and PR back. ### Make Targets +- `make deps`: Install development dependencies into `Github Dark/node_modules` - `make build`: Build `github-dark.user.css` - `make install`: Install `github-dark.user.css` - `make lint`: Run linters @@ -133,9 +139,18 @@ Lesser used targets include: - `make authors`: Regenerate the `AUTHORS` file based on git history - `make update`: Update dependencies +- `make`: Alias for `make build` + +Internal use only targets include: + - `make patch`: Increment the patch version, create a commit and push it - `make minor`: Increment the minor version, create a commit and push it - `make major`: Increment the major version, create a commit and push it -- `make`: Alias for `make build` -Thanks to all that have [contributed](./AUTHORS) so far! And thanks for the shoutout on the [JS Party](https://changelog.com/jsparty/20#transcript-71) podcast! +## Notes + +- If you're using a custom domain for GitHub Enterprise, be sure to include it through a `@-moz-document` rule (Firefox) or add it to the `Applies to` section in (Chrome). See + +- Any additions into `github-dark.user.css` are lost on `make build` + +Thanks to all our [contributors](./AUTHORS) so far! And thanks for the shoutout on the [JS Party](https://changelog.com/jsparty/20#transcript-71) podcast! diff --git a/src/gen/mappings.js b/src/gen/mappings.js index 4cd6e9b46..77129cfc6 100644 --- a/src/gen/mappings.js +++ b/src/gen/mappings.js @@ -1,4 +1,12 @@ module.exports.mappings = { + // ========================================================================== + // Short How-to + // `$border: value`: Any occurance of `value` in a `border` property. + // `$background: value` Any occurance of `value` in a `background` property. + // `$box-shadow: value` Any occurance of `value` in a `box-shadow` property. + // `$color: value`: Any occurance of `value`. + // `color | fill | background | etc: value`: Any occurance of `value` in a `color | fill | background | etc` property. + // // ========================================================================== // Color anywhere // ==========================================================================