Skip to content

Commit

Permalink
more edits
Browse files Browse the repository at this point in the history
  • Loading branch information
thescientist13 committed Nov 8, 2024
1 parent 6063d69 commit ecc2805
Show file tree
Hide file tree
Showing 4 changed files with 20 additions and 13 deletions.
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ If asking a question, looking for help, or you have an idea for Greenwood, pleas

## Type of Change

<!-- Please write out from of the following options: -->
<!-- Please select from one of the following options: -->
<!-- Feature / Bug / Other -->

## Summary
Expand Down
2 changes: 1 addition & 1 deletion .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ We love contributions and appreciate any help you can offer!

## Documentation

<!-- if this issue has been labeled as documentation, please submit a PR to our website repo -->
<!-- if this issue has been labeled with documentation, please make sure submit a PR to our website repo and link it -->
<!-- https://github.com/ProjectEvergreen/www.greenwoodjs.dev -->

## Summary of Changes
Expand Down
19 changes: 12 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,18 +21,18 @@ To develop for the project, you'll want to follow these steps:

### Patch Package

Generally we prefer to develop new features in the context of a project, working directly within _node_modules_ and validating the behavior first hand. Since Greenwood runs on plugins, just like any other user of Greenwood, a lot can often be achieved by just creating a custom plugin in a project's _greenwood.config.js_ file.
Generally we prefer to develop new features in the context of a project, working directly within _node_modules_ and validating the behavior or fix first hand. Since Greenwood runs on plugins, just like any other user of Greenwood, a lot can often be achieved by just creating a custom plugin in a project's _greenwood.config.js_ file.

If changes to _node_modules_ are needed, use [**patch-package**](https://www.npmjs.com/package/patch-package) to create a snapshot of those changes and provide that repo and patch along with your PR.


### Testing

#### Test Cases

Greenwood relies on a large set of test suites that are very behavior based, in that we scaffold out a full Greenwood project, including a _greenwood.config.js_. Combined with mocha for testing and [**gallinago**](https://github.com/thescientist13/gallinago) for running Greenwood commands, any combination of configuration, project structure, and Greenwood command can be tested for its output. (in other words, we are more E2E / BDD testing, not unit testing).
Greenwood relies on a large set of test suites that are very behavior based, in that we can scaffold out a full Greenwood project, including a _greenwood.config.js_ and run any of Greenwood's commands over the project files. Combined with mocha for testing and [**gallinago**](https://github.com/thescientist13/gallinago) for running Greenwood commands, any combination of configuration, project structure, and Greenwood command can be tested for its output. (in other words, we favor E2E / BDD testing, as opposed to unit testing).

Here an example test case:

```js
import chai from 'chai';
import { JSDOM } from 'jsdom';
Expand Down Expand Up @@ -94,11 +94,13 @@ describe('Build Greenwood With: ', function() {
### Running Tests
To run tests in watch mode, use:
```shell
$ yarn test:tdd
```
To verify compliance with coverage and watermark thresholds (what CI server runs), use:
```shell
$ yarn test
```
Expand All @@ -114,6 +116,7 @@ Below are some tips to help with running / debugging tests:
### Writing Tests
Test cases follow a convention starting with the command (e.g. `build`) and and the capability and features being tested, like configuration with a particular option (e.g. `port`):
```shell
<command>.<capability>.<feature>-<modifier>.spec.js
```
Expand All @@ -137,7 +140,7 @@ Test cases that exercise custom loaders (like TypeScript, JSX plugins) for SSR a
runner = new Runner(false, true);
});
```
1. Use `yarn test:loaders` npm script
1. Use the `yarn test:loaders` npm script
#### Notes
Expand All @@ -150,7 +153,8 @@ Here are some things to keep in mind while writing your tests, due to the asynch

To add and remove packages for any workspace, make sure you `cd` into the directory with the _package.json_ first before running `yarn add` or `yarn remove`.

For example
For example:

```shell
$ cd packages/cli
$ yarn add <package>
Expand Down Expand Up @@ -210,15 +214,15 @@ We take advantage of quite a few features on GitHub to assist in tracking issues
### Project Boards
Our [sequentially named project boards](https://github.com/ProjectEvergreen/greenwood/projects) help us organize work into buckets that will generally include a small handful of "top line" goals and objectives we would like to focus on for that particular time box. It also serves as a catch-all for the usual work and bug fixes that happens throughout general maintenance of the project. Additionally, we leverage this as a means to shine insight into good opportunities for those interested in contributing as what the Greenwood team would appreciate help with the most.
Our [sequentially named project boards](https://github.com/ProjectEvergreen/greenwood/projects) help us organize work into buckets that will generally include a small handful of "top line" goals and objectives we would like to focus on for that particular phase of work. It also serves as a catch-all for the usual work and bug fixes that happens throughout general maintenance of the project. Additionally, we leverage this as a means to shine insight into good opportunities for those interested in contributing as to what the Greenwood team would appreciate help with the most.
### Discussions
We believe good collaboration starts with good communication. As with most of the open source community, Greenwood is a 100% volunteer project and so we understand the importance of respecting everyone's [time and expectations](https://jason.energy/setting-expectations/) when it comes to contributing and investing in a project. Although we don't mind issues being made, unless the issue is clearly actionable and falls in-line with the motivations and trajectory of the project, then feel free to go ahead an open a [Discussion](https://github.com/ProjectEvergreen/greenwood/discussions) first.

We encourage discussions as we believe it is better to hash out technical discussions and proposals ahead of time since coding and reviewing PRs are very time consuming activities. As maintainers, we want to make sure everyone gets the time they are desire for contributing and this this workflow helps us plan our time in advance to best ensure a smooth flow of contributions through the project.

> _Put another way, we like to think of this approach as **measure twice, cut once**._
> _Put another way, we like to think of this approach as **measuring twice, cut once**._

### Issues

Expand All @@ -232,6 +236,7 @@ Our standard issue template requests some of the following information to be pre
### Pull Requests

Pull requests are the best! To best help facilitate contributions to the project, here are some requests:

- We generally prefer an issue be opened first, to help facilitate general discussion outside of the code review process itself and align on the ask and any expectations. However, for typos in docs and minor "chore" like tasks a PR is usually sufficient. When in doubt, open an issue.
- For bugs, please consider reviewing the issue tracker first.
- For branching, we generally follow the convention `<issue-label>/issue-<number>-<issue-title>`, e.g. _bug/issue-12-fixed-bug-with-yada-yada-yada_
Expand Down
10 changes: 6 additions & 4 deletions packages/plugin-typescript/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,23 @@

## Overview

A Greenwood plugin for writing [**TypeScript**](https://www.typescriptlang.org/). There is still a [little more work](https://github.com/ProjectEvergreen/greenwood/issues/658) we would like to do but this plugin should be suitable for general usage.
A Greenwood plugin for writing [**TypeScript**](https://www.typescriptlang.org/). For more information and complete docs on Greenwood, please visit [our website](https://www.greenwoodjs.dev).

> This package assumes you already have `@greenwood/cli` installed.
## Installation

You can use your favorite JavaScript package manager to install this package.

_examples:_
```bash
# npm
npm install @greenwood/plugin-typescript --save-dev
$ npm i -D @greenwood/plugin-typescript

# yarn
yarn add @greenwood/plugin-typescript --dev
$ yarn add @greenwood/plugin-typescript --dev

# pnpm
$ pnpm add -D @greenwood/plugin-typescript
```

## Usage
Expand Down

0 comments on commit ecc2805

Please sign in to comment.