Contributing to NgcEsbuild

January 19, 2022 ยท View on GitHub

:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:

This document contains the main rules of contributing to the project.

Table Of Contents

What should I know before I get started?

How Can I Contribute?

Styleguides

What should I know before I get started?

Ngc-Esbuild project

This project is based on the EsBuild compiler created in Golang. Therefore this is a super-fast builder implementation for Angular, with some limitations. We have to follow the primary Esbuild lifecycle while working on our builder.

Plugin Conventions

NgcEsbuild uses the Esbuild plugin system. Which is a dynamic linking technique, that is responsible for loading codes through the compilation process.

There are a few conventions that have developed over time around plugins:

  • Plugin directory is: bin/plugin.
  • The name of plugin files follow this schema: esbuild-plugin-[name].js
  • Plugin files contain one default export, like this:
module.exports = (instance) => {};
  • Default export gets a reference of the main class (instance). You can access
    the main process through this instance variable.

Design Decisions

The main goal is speed!
We currently use native Javascript for development. We are trying to avoid too many dependencies, only using the necessary third-party packages. The cause of it is too many packages create a slower program.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues.

Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.

How Do I Submit A (Good) Bug Report?

Explain the problem and include additional details to help maintainers reproduce the problem:

  • Use a clear and descriptive title for the issue to identify the problem.
  • Describe the exact steps which reproduce the problem in as many details as possible. For example, start by explaining how you started the program, e.g. which command exactly you used in the terminal, and so on.
  • Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use Markdown code blocks.
  • Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
  • Explain which behavior you expected to see instead and why.
  • Include screenshots and animated GIFs which show you following the described steps and clearly demonstrate the problem. If you use the keyboard while following the steps, record the GIF with the Keybinding Resolver shown. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.

Pull Requests

The process described here has several goals:

  • Maintain the package quality
  • Fix problems that are important to users

Styleguides

Git Commit Messages

  • Use the present tense ("Add feature" not "Added feature")
  • Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
  • Limit the first line to 72 characters or less
  • Reference issues and pull requests liberally after the first line
  • When only changing documentation, include [ci skip] in the commit title
  • Consider starting the commit message with an applicable emoji:
    • :art: :art: when improving the format/structure of the code
    • :racehorse: :racehorse: when improving performance
    • :non-potable_water: :non-potable_water: when plugging memory leaks
    • :memo: :memo: when writing docs
    • :penguin: :penguin: when fixing something on Linux
    • :apple: :apple: when fixing something on macOS
    • :checkered_flag: :checkered_flag: when fixing something on Windows
    • :bug: :bug: when fixing a bug
    • :fire: :fire: when removing code or files
    • :green_heart: :green_heart: when fixing the CI build
    • :white_check_mark: :white_check_mark: when adding tests
    • :lock: :lock: when dealing with security
    • :arrow_up: :arrow_up: when upgrading dependencies
    • :arrow_down: :arrow_down: when downgrading dependencies
    • :shirt: :shirt: when removing linter warnings

JavaScript Styleguide

  • Prefer the object spread operator ({...anotherObj}) to Object.assign()
  • Inline exports with expressions whenever possible 
    // Use this:
module.exports = class ClassName {

}

// Instead of:
class ClassName {

}
module.export = ClassName;
  • Place requires in the following order:
    • Built in Node Modules (such as path)
    • Local Modules (using relative paths)
  • Place class properties in the following order:
    • Class methods and properties (methods starting with static)
    • Instance methods and properties

Specs Styleguide

  • Treat describe as a noun or situation.
  • Treat it as a statement about state or how an operation changes state.

Documentation Styleguide

  • Use Markdown.
  • Reference methods and classes in markdown with the custom {} notation:
    • Reference classes with {ClassName}
    • Reference instance methods with {ClassName::methodName}
    • Reference class methods with {ClassName.methodName}