DevelopmentWhat you need to know to help develop LambdaLog.

If you are planning to do any development on LambdaLog, whether for testing or submitting a pull request, this will guide you through the steps.

Cloning

Before you can start development on the code, you'll need to clone the repo.

If you are planning to submit a pull request:

Fork the node-lambda-log repo.
Clone down the code from your fork to your machine.

If you are just testing the code or want to play around:

Clone the node-lambda-log repo to your machine.

Setup

Now that you have the code cloned to your local machine, let's get everything set up for development.

It's highly recommended to use VSCode for development work on LambdaLog. This repo contains workspace settings and recommended extensions for VSCode to ensure that your environment is setup correctly and the code style/rules are enforced. If you are to use another editor, ensure that you setup your environment to match.

Requirements:

Ensure that you have the following requirements before beginning:

Install git if you do not already have it.
Install the latest LTS of Node. I strongly recommend using NVM for this.

Install Dependencies:

Open terminal and cd to the root of this repo you cloned.
Run npm i to install the dependencies for LambdaLog.

Setup VSCode:

Open the repo's folder in VSCode. You will be prompted to install a couple of extensions if you do not already have them installed. Ensure to accept each one.
You may be prompted with another dialog to allow usage of the project installed version of ESLint. You should click "Allow" on this dialog. If you do not receive a dialog, follow the documentation here.

You are now able to start development!

Other Information

Structure

 1.
 2└── node-lamda-log/
 3    ├── lib/
 4    │   ├── LambdaLog.js
 5    │   ├── LambdaLog.test.js
 6    │   ├── LogMessage.js
 7    │   └── LogMessage.test.js
 8    ├── site/
 9    ├── index.js
10    ├── index.test.js
11    └── package.json

The entrypoint for this module is index.js.
The classes used by this module are defined in the lib/ directory.
Files that end with .test.js are the Jest unit tests for that file.
All files in the site/ directory are for this website. See Website below for more information.

There are other files that are less important to the development of LambdaLog but have other purposes:

.github/workflows/ — Contains the workflow definitions for building and publishing this package and website on Github Actions.
.vscode/extensions.json — The recommended VSCode extensions to prompt for installation when the workspace is opened.
.vscode/settings.json — The VSCode settings for this workspace.
.eslintrc.yml — The ESLint configuration for this project.
.gitignore — Ignore patterns of files/folders that should not be committed to the repository.
.npmignore — Ignore patterns of files/folders that are in git, but should not be packaged when publishing the package to NPM.
.releaserc — Configuration for Semantic Release.
CHANGELOG.md — Changes between versions of LambdaLog. Do not update this file, it is updated automatically by Semantic Release.
commitlint.config.js — Configuration for commitlint to enforce conventional commits.
jest.config.js — Configuration for Jest.
LICENSE — The license for this project.
README.md — The main readme for this project.

Tests

Unit testing is important to ensure this module functions the way it was intended between changes and different versions of Node. Tests are written using Jest and executed on every pull request and merge into the master branch. Tests are separated by file and live alongside the main file with a .test.js file extension.

There should always be 100% test coverage including branches.

To run the tests, execute the following command in terminal within the root of this project:

1npm test

If all of the tests pass, you will be presented with table that shows the test coverage. Ensure you have 100% coverage across the board prior to opening a pull request.

Conventional Commits

This project uses Semantic Release to publish new versions to the NPM registry. Semantic Release is able to determine whether to release a new version and what the version number should be by evaluating the commit messages made since the prior release. This is why it's extremely important to use conventional commit messages for each of the commits made. While this information is available on their websites, here is a quick overview.

The conventional commit message structure:

1<type>[optional scope]: <description>
2
3[optional body]
4
5[optional footer(s)]

Semantic Release will only release a new version of the module if the feat: or fix: types are used. All other types will not trigger a release.

feat: — A new feature or improvement. This will cause Semantic Release to bump the minor version ([major].[minor].[patch]) of the module.
fix: — A bug fix. This will cause Semantic Release to bump the patch version ([major].[minor].[patch]) of the module.

If the change imposes a breaking change, BREAKING CHANGE should be included at the end of the commit message body. This will trigger Semantic Release to bump the major version ([major].[minor].[patch]) of the module. This will work with any "type".

Other types:

build: — A change that affects the build process of the module.
chore: — Any change that does not fit with any other type.
ci: — Used by the CI/CD to note a change that was committed during build.
docs: — Updates to documentation or README.
style: — A stylistic change to the code (ex. using semi-colons).
reactor: — A refactor of the code that does not change the functionality.
perf: — A change that increases the performance of a specific piece of functionality.
test: — Any change or addition to the unit tests.

CommitLint

This module is setup with Husky and CommitLint to help enforce the usage of Conventional Commit messages. While this should automatically prevent commit messages that are not in the proper format, there is, at times, issues on certain platforms, git versions, and configurations where this git hook will not run. This is why it's important to ensure you are writing proper commit messages.

Examples of proper commit messages

1feat: add new option `dynamicMeta` to LambdaLog class

Bumps the minor version of the module.

1fix: remove extra space in error message

Bumps the patch version of the module.

1feat: remove existing log tags in favor of customizable tags
2
3BREAKING CHANGE

Bumps the mahor version of the module.

Commiting and Pull Requests

First off, thank you for your contributions! Before you make any commits and open a pull request, please ensure you have completed the following:

Before Committing:

Ensure there are no ESLint errors or warnings within the code and that it matches the style of the existing code.
You are writing your commit messages using conventional commits.

Before opening a Pull Request:

Ensure you have written and/or updated the unit tests for your changes.
Test and branch coverage remains at 100%.
Documentation has been updated if applicable.

CI/CD and Publishing

LambdaLog uses GitHub Actions to build and publish this module to the NPM registry. When a new pull request is opened, a subset of the build process will run to verify code coverage and ensure it meets the guidelines.

When a pull request is merged into master, the build process will:

Run all tests to ensure they pass and meet 100% coverage.
Use Semantic Release to:
- Determine the new version number of the module.
- Build out the changelog.
- Package and publish the module to the NPM registry.
- Update the changelog and package.json in the repository.
- Create a new release on Github.
Build the website and push the built site to the respository.

Website

This website's source code is part of the node-lambda-log repo and is hosted on Vercel. Here is some basic information about the website:

The site is built using Next.js.
All the documentation lives in MDX (Markdown with JSX) files within site/pages/docs.
The site will be deployed with every merge into master.