Skip to content

Commit

Permalink
Rewrap all project markdown files
Browse files Browse the repository at this point in the history
  • Loading branch information
@lelia
lelia committed Dec 15, 2022
1 parent 88c8f10 commit 804b402
Show file tree
Hide file tree
Showing 4 changed files with 115 additions and 71 deletions.
12 changes: 8 additions & 4 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
and this project adheres to [Semantic
Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

Expand Down Expand Up @@ -32,6 +33,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Build and dependency fixes, Docker enhancements
- Cleaned up and improved Goals splash page

[unreleased]: https://github.com/wayfair-incubator/aux-eng-playbook/compare/v0.0.2...HEAD
[0.0.2]: https://github.com/wayfair-incubator/aux-eng-playbook/releases/tag/v0.0.2
[0.0.1]: https://github.com/wayfair-incubator/aux-eng-playbook/releases/tag/v0.0.1
[unreleased]:
https://github.com/wayfair-incubator/aux-eng-playbook/compare/v0.0.2...HEAD
[0.0.2]:
https://github.com/wayfair-incubator/aux-eng-playbook/releases/tag/v0.0.2
[0.0.1]:
https://github.com/wayfair-incubator/aux-eng-playbook/releases/tag/v0.0.1
40 changes: 20 additions & 20 deletions CODE_OF_CONDUCT.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, caste, color, religion, or sexual identity
and orientation.
nationality, personal appearance, race, caste, color, religion, or sexual
identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
Expand All @@ -23,17 +23,17 @@ community include:
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the
overall community
* Focusing on what is best not just for us as individuals, but for the overall
community

Examples of unacceptable behavior include:

* The use of sexualized language or imagery, and sexual attention or
advances of any kind
* The use of sexualized language or imagery, and sexual attention or advances of
any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
address, without their explicit permission
* Publishing others' private information, such as a physical or email address,
without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting

Expand Down Expand Up @@ -61,8 +61,8 @@ representative at an online or offline event.

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
opensource@wayfair.com.
All complaints will be reviewed and investigated promptly and fairly.
opensource@wayfair.com. All complaints will be reviewed and investigated
promptly and fairly.

All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
Expand All @@ -83,15 +83,15 @@ behavior was inappropriate. A public apology may be requested.

### 2. Warning

**Community Impact**: A violation through a single incident or series
of actions.
**Community Impact**: A violation through a single incident or series of
actions.

**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
like social media. Violating these terms may lead to a temporary or permanent
ban.

### 3. Temporary Ban

Expand All @@ -110,21 +110,21 @@ Violating these terms may lead to a permanent ban.
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.

**Consequence**: A permanent ban from any sort of public interaction within
the community.
**Consequence**: A permanent ban from any sort of public interaction within the
community.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0].

Community Impact Guidelines were inspired by
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder][Mozilla CoC].

For answers to common questions about this code of conduct, see the FAQ at
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
at [https://www.contributor-covenant.org/translations][translations].
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
[https://www.contributor-covenant.org/translations][translations].

[homepage]: https://www.contributor-covenant.org
[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html
Expand Down
67 changes: 39 additions & 28 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,45 +1,56 @@
# How to Contribute

Thanks for your interest in contributing to the Aux Eng Playbook! Here are a few general guidelines on contributing and
reporting bugs that we ask you to review. Following these guidelines helps to communicate that you respect the time of
the contributors managing and developing this open source project. In return, they should reciprocate that respect in
addressing your issue, assessing changes, and helping you finalize your pull requests. In that spirit of mutual respect,
we endeavour to review incoming issues and pull requests within 10 days, and will close any lingering issues or pull
requests after 60 days of inactivity.

Please note that all of your interactions in the project are subject to our [Code of Conduct](CODE_OF_CONDUCT.md). This
includes creation of issues or pull requests, commenting on issues or pull requests, and extends to all interactions in
any real-time space (eg. Slack, Discord, etc).
Thanks for your interest in contributing to the Aux Eng Playbook! Here are a few
general guidelines on contributing and reporting bugs that we ask you to review.
Following these guidelines helps to communicate that you respect the time of the
contributors managing and developing this open source project. In return, they
should reciprocate that respect in addressing your issue, assessing changes, and
helping you finalize your pull requests. In that spirit of mutual respect, we
endeavour to review incoming issues and pull requests within 10 days, and will
close any lingering issues or pull requests after 60 days of inactivity.

Please note that all of your interactions in the project are subject to our
[Code of Conduct](CODE_OF_CONDUCT.md). This includes creation of issues or pull
requests, commenting on issues or pull requests, and extends to all interactions
in any real-time space (eg. Slack, Discord, etc).

## Reporting Issues

Before reporting a new issue, please ensure that the issue was not already reported or fixed by searching through our
[issues list](https://github.com/wayfair-incubator/aux-eng-playbook/issues).
Before reporting a new issue, please ensure that the issue was not already
reported or fixed by searching through our [issues
list](https://github.com/wayfair-incubator/aux-eng-playbook/issues).

When creating a new issue, please be sure to include a **title and clear description**, as much relevant information as
possible, and, if possible, a test case.
When creating a new issue, please be sure to include a **title and clear
description**, as much relevant information as possible, and, if possible, a
test case.

**If you discover a security bug, please do not report it through GitHub. Instead, please see security procedures in
[SECURITY.md](SECURITY.md).**
**If you discover a security bug, please do not report it through GitHub.
Instead, please see security procedures in [SECURITY.md](SECURITY.md).**

## Sending Pull Requests

Before sending a new pull request, take a look at existing pull requests and issues to see if the proposed change or fix
has been discussed in the past, or if the change was already implemented but not yet released.
Before sending a new pull request, take a look at existing pull requests and
issues to see if the proposed change or fix has been discussed in the past, or
if the change was already implemented but not yet released.

We expect new pull requests to include tests for any affected behavior, and, as we follow semantic versioning, we may
reserve breaking changes until the next major version release.
We expect new pull requests to include tests for any affected behavior, and, as
we follow semantic versioning, we may reserve breaking changes until the next
major version release.

## Other Ways to Contribute

We welcome anyone that wants to contribute to the Aux Eng Playbook to triage and reply to open issues to help troubleshoot
and fix existing bugs. Here is what you can do:

- Help ensure that existing issues follows the recommendations from the _[Reporting Issues](#reporting-issues)_ section,
providing feedback to the issue's author on what might be missing.
- Review and update the existing content of our [Wiki](https://github.com/wayfair-incubator/aux-eng-playbook/wiki) with up-to-date
instructions and code samples.
- Review existing pull requests, and testing patches against real existing applications that use the Aux Eng Playbook.
We welcome anyone that wants to contribute to the Aux Eng Playbook to triage and
reply to open issues to help troubleshoot and fix existing bugs. Here is what
you can do:

- Help ensure that existing issues follows the recommendations from the
_[Reporting Issues](#reporting-issues)_ section, providing feedback to the
issue's author on what might be missing.
- Review and update the existing content of our
[Wiki](https://github.com/wayfair-incubator/aux-eng-playbook/wiki) with
up-to-date instructions and code samples.
- Review existing pull requests, and testing patches against real existing
applications that use the Aux Eng Playbook.
- Write a test, or add a missing test case to an existing test.

Thanks again for your interest on contributing to the Aux Eng Playbook!
Expand Down
67 changes: 48 additions & 19 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,23 @@

[![Deploy](https://github.com/wayfair-incubator/aux-eng-playbook/actions/workflows/deploy.yml/badge.svg?branch=main)](https://github.com/wayfair-incubator/aux-eng-playbook/actions/workflows/deploy.yml)
[![Release](https://img.shields.io/github/v/release/wayfair-incubator/aux-eng-playbook?display_name=tag)](https://github.com/wayfair-incubator/aux-eng-playbook/releases)
[![License: BSD 0-Clause](https://img.shields.io/badge/License-BSD%200--Clause-orange.svg)](LICENSE)
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-24B8EE.svg)](CODE_OF_CONDUCT.md)
[![License: BSD
0-Clause](https://img.shields.io/badge/License-BSD%200--Clause-orange.svg)](LICENSE)
[![Contributor
Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-24B8EE.svg)](CODE_OF_CONDUCT.md)
[![Maintainer](https://img.shields.io/badge/Maintainer-Wayfair-7F187F)](https://wayfair.github.io)

A playbook for technologists interested in introducing [Auxiliary Engineering](https://www.aboutwayfair.com/tech-innovation/what-is-auxiliary-engineering) to their engineering organization. The [Aux Eng Playbook](https://github.com/wayfair-incubator/aux-eng-playbook) aims to document Wayfair Tech's pioneering implementation of Aux Eng programs while sharing key takeaways, learnings, and recipes for success.
A playbook for technologists interested in introducing [Auxiliary
Engineering](https://www.aboutwayfair.com/tech-innovation/what-is-auxiliary-engineering)
to their engineering organization. The [Aux Eng
Playbook](https://github.com/wayfair-incubator/aux-eng-playbook) aims to
document Wayfair Tech's pioneering implementation of Aux Eng programs while
sharing key takeaways, learnings, and recipes for success.

## 🚀 Quick Start

To get started editing this site, you'll need Node v14+, and _preferably_ v19. We recommend using [nvm](https://github.com/nvm-sh/nvm).
To get started editing this site, you'll need Node v14+, and _preferably_ v19.
We recommend using [nvm](https://github.com/nvm-sh/nvm).

Once that's installed, you'll need [`yarn`](https://yarnpkg.com/) as well.

Expand All @@ -36,15 +44,19 @@ You can now view Aux Eng Playbook in the browser.

```

You can edit the site by editing the files in `src/`. This site uses CSS, JS, and [css-in-js](https://cssinjs.org/).
You can edit the site by editing the files in `src/`. This site uses CSS, JS,
and [css-in-js](https://cssinjs.org/).

> 💡 Note that for most images, you'll want to run `yarn build` before they show up correctly on the development site.
> 💡 Note that for most images, you'll want to run `yarn build` before they show
> up correctly on the development site.
## 🐳 Docker Setup

If you'd prefer to develop within a `node:19-alpine` container, this project also supports using Docker Compose with hot-reloading capabilites for Gatsby.
If you'd prefer to develop within a `node:19-alpine` container, this project
also supports using Docker Compose with hot-reloading capabilites for Gatsby.

First, make sure you have both [docker](https://docs.docker.com/engine/install/) and [docker-compose](https://docs.docker.com/compose/install/) installed.
First, make sure you have both [docker](https://docs.docker.com/engine/install/)
and [docker-compose](https://docs.docker.com/compose/install/) installed.

To bring up the `gastby` development server, run:

Expand All @@ -53,9 +65,15 @@ docker-compose down
docker-compose up -d develop # Remove the -d flag if you don't witsh to daemonize the container
```

Once the server is up and running, when you make local changes to your `gatsby` site content, the changes should hot-reload in your containerized instance, accessible in a browser at `http://localhost:8000`. Note that it's easier to observe the hot-reloading functionality in action when the container is not daemonized.
Once the server is up and running, when you make local changes to your `gatsby`
site content, the changes should hot-reload in your containerized instance,
accessible in a browser at `http://localhost:8000`. Note that it's easier to
observe the hot-reloading functionality in action when the container is not
daemonized.

If you'd like to interact with the [gatsby-cli](https://www.gatsbyjs.com/docs/reference/gatsby-cli/) directly, you can also run commands like:
If you'd like to interact with the
[gatsby-cli](https://www.gatsbyjs.com/docs/reference/gatsby-cli/) directly, you
can also run commands like:

```shell
docker-compose run gatsby --help
Expand All @@ -64,32 +82,43 @@ docker-compose run gatsby info # Example commmand to get environment information

## Contributing to Docs

If you're here to write some of our plentiful documentation, use these foolproof steps:
If you're here to write some of our plentiful documentation, use these foolproof
steps:

1. Ensure you've completed the [Quick Start](#-quick-start) above, and have a server running.
1. Ensure you've completed the [Quick Start](#-quick-start) above, and have a
server running.
1. Make a new branch for your new document post.
1. Create a new directory (or sub-directory, or sub-sub-directory) in `src/docs` like `my-doc`
1. Create an `index.md` file in `src/docs/my-doc` (or whatever you named your doc). This will be your document's markdown page.
1. Write the [frontmatter](https://github.com/remarkjs/remark-frontmatter#use) for the page like so:
1. Create a new directory (or sub-directory, or sub-sub-directory) in `src/docs`
like `my-doc`
1. Create an `index.md` file in `src/docs/my-doc` (or whatever you named your
doc). This will be your document's markdown page.
1. Write the [frontmatter](https://github.com/remarkjs/remark-frontmatter#use)
for the page like so:

```markdown
---
title: "My Snazzy Article"
---
```

1. Optionally, include any assets you need (images, etc) alongside `index.md`, and reference them directly, eg: `[my-image](./my-image)`
1. Watch your markdown come to life in your browser by visiting the corresponding path to your document from `/docs` (in this case, we'd visit `docs/my-doc`)
1. Optionally, include any assets you need (images, etc) alongside `index.md`,
and reference them directly, eg: `[my-image](./my-image)`
1. Watch your markdown come to life in your browser by visiting the
corresponding path to your document from `/docs` (in this case, we'd visit
`docs/my-doc`)
1. When satisfied, commit the result for review.

## Deploying

As long as permissions work and everything is aligned in the stars, you ought to be able to deploy with:
As long as permissions work and everything is aligned in the stars, you ought to
be able to deploy with:

```shell
yarn deploy
```

## Troubleshooting

If you see strange behavior from developing or building the app, try `npx gatsby clean`. This should use the `gatsby-cli` to clean out frayed node modules or other unexpected hitches.
If you see strange behavior from developing or building the app, try `npx gatsby
clean`. This should use the `gatsby-cli` to clean out frayed node modules or
other unexpected hitches.

0 comments on commit 804b402

Please sign in to comment.