From e56299b771e17978ebf66343022ed27703dd8b28 Mon Sep 17 00:00:00 2001 From: Jeldrik Hanschke Date: Sun, 6 Dec 2020 19:40:27 +0100 Subject: [PATCH] add contributing docs --- CONTRIBUTING.md | 60 +++++++++++++++++++ README.md | 17 ++---- src/index.ts | 2 +- .../travis-ci.ts} | 2 +- 4 files changed, 66 insertions(+), 15 deletions(-) create mode 100644 CONTRIBUTING.md rename src/{utils/parse-travis-ci-config.ts => parser/travis-ci.ts} (98%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e13761e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,60 @@ +# How To Contribute + +## Installation + +- `git clone https://github.com/jelhan/create-github-actions-setup-for-ember-addon.git` +- `cd create-github-actions-setup-for-ember-addon` +- `yarn install` + +## Architecture + +GitHub Actions CI workflow is created based on a template writen in [EJS](https://ejs.co/). +It's located in `templates/.github/workflows/ci.yml`. + +A configuration object is used to generate a concrete workflow based on the +template. It is defined by `ConfigurationInterface`. + +The data used is extracted from existing configuration files in the project. +The utility functions responsible for parsing existing configurations are +called parser. They are located in `src/parser/`. So far only TravisCI +configuration (`.travis.yml`) is supported. + +If no configuration file supported by any available parser is found, default +values are used. + +## Running latest development + +The project is written in TypeScript. To use latest development you must first +compile the code to JavaScript. Run `yarn compile` to do so. + +Afterwards you can run latest development on any project. To do so change +current working directory to the project and afterwards execute the script +using a local path: +`/path/to/create-github-actions-setup-for-ember-addon/bin/create-github-actions-setup-for-ember-addon` + +## Linting + +The project uses ESLint for linting and Prettier for code formatting. Prettier +is integrated as an ESLint plugin. + +Execute `yarn lint` to run linting and `yarn lint --fix` to automatically fix +linting issues. The latter is especially helpful to prettify the code. + +## Running tests + +The tests are executed with `yarn test`. The command also takes care of +compiling the TypeScript to JavaScript before executing the script. + +The Tests are written with [jest](https://jestjs.io/). + +The tests use [snapshot testing](https://jestjs.io/docs/en/snapshot-testing). +A snapshot of the created GitHub Actions CI workflow is created for each test +scenario. It's compared against snapshots created before. The snapshots are +checked into the repository and located at `tests/acceptance/__snapshots__`. + +The snaphot-based tests are expected to fail whenever the created GitHub +Actions CI workflow changes. In many cases that changes may be expected. If so +the snapshots must be updated. Run `yarn test -u` to do so. + +Please double check that all changes to snapshots are as expected by your +change before committing the changes. diff --git a/README.md b/README.md index 0adb69e..564dce3 100644 --- a/README.md +++ b/README.md @@ -25,19 +25,10 @@ Merge requests are very much appreciated. Parts that could be improved are: - Only a very limited subset of common customizations of the default TravisCI configuration is supported. Would love to support more common patterns. - The script could be extended to allow the user to set configuration variables with command line flags rather than extracting them from an existing TravisCI configuration. -### Running latest development - -The script is written in TypeScript. Therefore development branch can not be directly executed unless using [ts-node](https://github.com/TypeStrong/ts-node). - -1. Compile TypScript to Javascript: `yarn compile` -2. Change current working directory to the root of the project you want to setup GitHub Actions on. -3. Run the script: `/path/to/script/bin/create-github-actions-setup-for-ember-addon` - -### Testing - -Tests are written with [jest](https://jestjs.io/) using [Snapshots Testing](https://jestjs.io/docs/en/snapshot-testing). A test ist autogenerated for every file in `tests/fixtures`. Please double check that the generated snapshot is correct when adding an additional file. Snapshot tests are passing if no snapshot exists yet. - -The tests are executed by `yarn test`. +Contributing documentation is provided in [CONTRIBUTING.md](CONTRIBUTING.md) +to lower entry barrier. In case you face additional questions do not hesitate +to either open an issue or contact me (@jelhan) on +[Ember Community Discord](https://discord.gg/emberjs). ## License diff --git a/src/index.ts b/src/index.ts index 924dfa7..f6d9f66 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,7 +1,7 @@ import debug from './utils/debug'; import ejs from 'ejs'; import fs from 'fs'; -import parseTravisCiConfig from './utils/parse-travis-ci-config'; +import parseTravisCiConfig from './parser/travis-ci'; import path from 'path'; import process from 'process'; diff --git a/src/utils/parse-travis-ci-config.ts b/src/parser/travis-ci.ts similarity index 98% rename from src/utils/parse-travis-ci-config.ts rename to src/parser/travis-ci.ts index 70526b4..7605ac3 100644 --- a/src/utils/parse-travis-ci-config.ts +++ b/src/parser/travis-ci.ts @@ -1,5 +1,5 @@ import { ConfigurationInterface } from '../index'; -import debug from './debug'; +import debug from '../utils/debug'; import fs from 'fs'; import path from 'path'; import process from 'process';