Skip to content

Latest commit

 

History

History
48 lines (27 loc) · 3.27 KB

CONTRIBUTING.md

File metadata and controls

48 lines (27 loc) · 3.27 KB
Raw

Contributing

This package is built using the generator framework provided by Yeoman. Yeoman is a scaffolding tool which helps you to build generators to scaffold your projects. This generator is written in TypeScript.

Table of Contents

Getting started

It is highly recommended to familiarise yourself with Yeoman and their documentation on creating an accelerator before contributing to this repository.

Repository anatomy

The Yeoman generator source code is within the src folder. There are two folders within this:

  • A common folder for common classes used across the generators
  • A generators folder containing a folder for each generator

This differs from the Yeoman documentation which has the generators folder at the root of the project. The reason for this is that the src folder contains TypeScript source files rather than the compiled JavaScript.

Another difference to be aware of is the fact that the main generator does not only interact with the file system but also the Azure DevOps API. Some of the Azure DevOps configuration which is passed to the API is stored in the definitions folder within the app generator.

Updating the templates

Simple changes - involving the raw source code used in the template process - can most likely be updated without updating the generator code.

You can find these files in the templates folder of the generator or sub-generator you wish to update. For example, changes to the code generated by the main generator can be done within the src/generators/app/templates folder.

Refer to the Yeoman documentation if unsure on template syntax.

Updating the generation process

Updating the generation process can be done by modifying the source code within the src folder. The entry point for each generator is the index.ts file. For more information on writing generators, refer to the Yeoman documentation.

You can compile your changes by running the TypeScript compiler. Run this in watch mode within Visual Studio Code by opening the command palette with ctrl + shift + p, selecting Tasks: Run Task and then tsc: watch - tsconfig.json.

Note that only compiling the TypeScript source will not update the template files in your build output. In order to do this, you must run the npm: build task.

Testing your changes

You can test your changes by running the generator locally. Note that you will most likely need to create a temporary Azure DevOps project for this purpose.

To run the generators, first run the npm build task. This will build the generator source code and output it to the root of the project. The .vscode/launch.json file in this repository has been updated to include several debug configurations. This means you can easily debug the generators within Visual Studio Code. You will to first run the main generator before you can debug the others. The debug configurations will use the generators within the debug folder at the root of the project.