Merge pull request #330 from gstrauss/minor-updates

minor updates

Author: gstrauss

README.md

@@ -6,11 +6,36 @@ This tool is built and deployed to https://ssl-config.mozilla.org/
 
 To be notified when the Mozilla [Server Side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS) configuration guidelines are updated (infrequent), use github notifications to subscribe to Releases on this repository (mozilla/ssl-config-generator).
 
-To modify and build this tool locally, please read on:
+To modify and build this tool locally, please see Installation and Development sections below.
 
+## JSON guidelines
+
+Each revision of the Mozilla Server Side TLS guidelines is published in a machine-readable format from this repository as a [JSON specification](/src/static/guidelines/) that can be found at [`/src/static/guidelines/`](/src/static/guidelines/) 📟
+
+## Changelog
+
+The [Changelog](/src/static/guidelines/CHANGELOG.md) that tracks the history of changes to Mozilla's configuration guidelines is available along the versioned JSON guideline files at [`/src/static/guidelines/CHANGELOG.md`](/src/static/guidelines/CHANGELOG.md) 🔬
+
+## Contributing
+
+The project is written in JavaScript, and uses Webpack for development and production builds.
+
+We keep a list of things that would make a great contribution tagged with [*help wanted*](https://github.com/mozilla/ssl-config-generator/labels/help%20wanted), [*good first issue*](https://github.com/mozilla/ssl-config-generator/labels/good%20first%20issue), and [*new software support*](https://github.com/mozilla/ssl-config-generator/labels/new%20software%20support) labels.
+
+If you'd like to see your favorite tool added or compatibility expanded, we're always happy to mentor a PR or receive a bug report to make the configs better for everyone.
+
+Even when you don't feel comfortable contributing actual templates, posting some nice verified configs or compatibility hints is equally welcome! 💝
+
+Get involved by sharing your ideas or joining the conversation in the [Discussions](https://github.com/mozilla/ssl-config-generator/discussions) tab. 🗨️
+
+This repository is governed by Mozilla's [Community Participation Guidelines](/CODE_OF_CONDUCT.md)
+so please make yourself familiar with it to get the idea of what level of developer etiquette and standards are expected across Mozilla projects.
 
 ## Installation
 
+NodeJS and npm are required to install and run the project locally:
+Node v22 is recommended and we use that in production, but the codebase may be compatible with other versions too.
+
 ```bash
 $ npm install
 ```
@@ -20,7 +45,7 @@ $ npm install
 Once you've installed, you can simply run:
 
 ```bash
-$ npm run watch
+$ npm start   # or: npm run watch
 ```
 
 This starts a local webserver that will automatically reload your changes.
@@ -58,54 +83,50 @@ All of the templates are written in javascript.  The configuration generator sup
 
 Highlighted items from src/js/state.js for use in templates.  See src/js/state.js for more.
 
-- `form.serverName` - Server Name
-- `form.serverVersion` - Server Version
-- `form.opensslVersion` - OpenSSL Version
+- `form.serverName` - display name of the server
+- `form.serverVersion` - requested server version
+- `form.opensslVersion` - requested OpenSSL version
 - `form.config` - configuration name ([ "modern" | "intermediate" | "old" ])
 - `form.hsts` - HTTP Strict Transport Security form checkbox (boolean true/false)
 - `form.ocsp` - OCSP Stapling form checkbox (boolean true/false)
 
 - `output.header` - description of rendered config
 - `output.link` - URL to rendered config
 - `output.protocols` - protocol list (e.g. zero or more of: "TLSv1" "TLSv1.1" "TLSv1.2" "TLSv1.3")
-- `output.ciphers` - cipher list
-- `output.cipherSuites` - cipher suites list
+- `output.ciphers` - TLSv1.2 (and older) cipher list
+- `output.cipherSuites` - TLSv1.3+ cipher suites list
 - `output.serverPreferredOrder` - enforce ServerPreference for ordering cipher list (boolean true/false)
 - `output.hstsMaxAge` - max-age (seconds) for Strict-Transport-Security: max-age=... HTTP response header
 - `output.hstsRedirectCode` - HTTP status code to use for HSTS redirect from http:// to https://
 - `output.latestVersion` - server latest version
 - `output.usesOpenssl` - server uses openssl (boolean true/false)
 - `output.usesDhe` - server might use (<= TLSv1.2 kDHE) Diffie-Hellmann key exchange (boolean true/false)
 - `output.dhCommand` - command to generate Diffie-Hellman (DH) parameters
-- `output.hasVersions` - server config has versions (boolean true/false)
-- `output.supportsConfigs` - supports modern, intermediate, old configs (boolean true/false)
+- `output.hasVersions` - config supports several server versions (boolean true/false)
 - `output.supportsHsts` - supports HTTP Strict Transport Security (HSTS) (boolean true/false)
 - `output.supportsOcspStapling` - server version supporting OCSP Stapling in config
 - `output.tls13` - server version supporting TLSv1.3
 - `output.tlsCurves` - groups/curves list
 
 ## Building
 
-Generate production files in `docs/` files by running
+Production builds have different CSP headers, included scripts, and version info added to the output, so to verify that locally you can inspect the exact production-level artifacts as used in deployment after running:
+
 
 ```bash
 $ npm run build
 ```
 
-However, doing so is not necessary for production deployment.
+However, this step is not necessary for production deployment.
+Automation publishes the production site via GitHub Pages, so once your PR merges the changes deploy within a minute or two.
 GitHub Pages are published upon commit to the master branch
 via .github/workflows/deploy-to-production.yml
 
-## Changelog
-
-The Changelog that captures the history of changes to Mozilla's recommendations
-as represented in the JSON guideline files can be found at [`/src/static/guidelines/CHANGELOG.md`](/src/static/guidelines/CHANGELOG.md)
-
 ## History
 
-The SSL Config Generator was kept in [the `mozilla/server-side-tls` repository](https://github.com/mozilla/server-side-tls/tree/last-revision-before-move)
-prior to mid 2019 at which point it was moved to this dedicated repository. It
-was initially created [at the end of 2014](https://github.com/mozilla/server-side-tls/commit/b201a1191ba38e6f933cd02a4f425f683ffa9be4)
+The SSL Config Generator was originally part of [`mozilla/server-side-tls@v5.0`](https://github.com/mozilla/server-side-tls/tree/12fda41) ([last-revision-before-move](https://github.com/mozilla/server-side-tls/tree/last-revision-before-move))
+prior to mid-2019 at which point it was moved to this dedicated repository. It
+was initially created [at the end of 2014](https://github.com/mozilla/server-side-tls/commit/b201a11)
 and [started out supporting Apache HTTP, Nginx and HAProxy](https://web.archive.org/web/20141026012016/https://mozilla.github.io/server-side-tls/ssl-config-generator/).
 
 ## Authors
@@ -116,4 +137,5 @@ and [started out supporting Apache HTTP, Nginx and HAProxy](https://web.archive.
 
 ## License
 
-* Mozilla Public License Version 2.0
+This software is licensed under the [MPL version 2.0](https://www.mozilla.org/MPL/). For more
+information, read this repository's [LICENSE](LICENSE).