[ISSUE-14] Improved README.md (#16)

* Fixed tool help and version information

* docs(issue-14): improved README.md

CHANGELOG.md

@@ -1,7 +0,0 @@
-# Changelog
-
-# V1.0
-
-[Link](https://github.com/lampajr/backporting/releases/tag/0.0.1)
-
-TODO

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 GitHub, Inc. and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1,5 +1,7 @@
-<h1 align="center">BPER: Git Backporter</h1>
+<h1 align="center">
-<h2 align="center">:outbox_tray: :inbox_tray:</h2>
+  BPER: Git Backporter </br>
+  :outbox_tray: :inbox_tray:
+</h1>
 
 <p align="center">
   <a href="https://github.com/lampajr/backporting">
@@ -19,13 +21,38 @@ Table of content
 * **[Usage](#usage)**
 * **[GitHub Action](#github-action)**
 * **[Limitations](#limitations)**
-* **[Contributions](#contributions)**
+* **[Contributions](#contributing)**
+* **[License](#license)**
 
 
 ## Usage
 
+This tool is released on the [public npm registry](https://www.npmjs.com/), therefore it can be easily installed using `npm`:
+
+```bash
+$ npm install -g @lampajr/bper
+```
+
+Then it can be used as any other command line tool:
+
+```bash
+$ bper -tb <branch> -pr <pull-request-url> -a <github-token> [-f <your-folder>]
+```
+
 ### Inputs
 
+This toold comes with some inputs that allow users to override the default behavior, here the full list of available inputs:
+
+| **Name**      | **Command**          | **Required** | **Description**                                                                                                                                        | **Default** |
+|---------------|----------------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
+| Version       | -V, --version        | -            | Current version of the tool                                                                                                                            |             |
+| Help          | -h, --help           | -            | Display the help message                                                                                                                               |             |
+| Target Branch | -tb, --target-branch | Y            | Branch where the changes must be backported to                                                                                                         |             |
+| Pull Request  | -pr, --pull-request  | Y            | Original pull request url, the one that must be backported, e.g., https://github.com/lampajr/backporting/pull/1                                        |             |
+| Auth          | -a, --auth           | N            | `GITHUB_TOKEN` or a `repo` scoped [Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) | ""          |
+| Folder        | -f, --folder         | N            | Local folder where the repo will be checked out, e.g., /tmp/folder                                                                                     | {cwd}/bp    |
+| Dry Run       | -d, --dry-run        | N            | If enabled the tool does not push nor create anything remotely, use this to skip PR creation                                                           | false       |
+
 ## GitHub Action
 
 This action can be used in any GitHub workflow, below you can find a simple example of manually triggered workflow backporting a specific pull request (provided as input).
@@ -70,4 +97,37 @@ For a complete description of all inputs see [Inputs section](#inputs).
 
 ## Limitations
 
-## Contributions
+**BPer** is in development mode, this means that it has many limitations right now. I'll try to summarize the most importan ones:
+
+- No way to override backporting pull request fields like body, reviewers and so on.
+- You can backport pull requests only.
+- It only works for [GitHub](https://github.com/).
+- Integrated in GitHub Actions CI/CD only.
+
+Based on these limitations, the next **Future Works** could be the following:
+- Give users the possibility to override/customize the backporting pull request.
+- Provide a way to backport single commit too (or a set of them), even if no original pull request is present.
+- Integrate this tool with other git management services (like GitLab and Bitbucket) to make it as generic as possible.
+- Provide some reusable GitHub workflows.
+
+## Contributing
+
+This is an open source project, and you are more than welcome to contribute :heart:!
+
+Every change must be submitted through a GitHub pull request (PR). Backporting uses continuous integration (CI). The CI runs checks against your branch after you submit the PR to ensure that your PR doesn’t introduce errors. If the CI identifies a potential problem, our friendly PR maintainers will help you resolve it.
+
+1. Fork it (https://github.com/lampajr/backporting).
+
+2. Create your feature branch: (git checkout -b feature).
+
+3. Commit your changes with a comment: (git commit -am 'Add some feature').
+
+4. Push to the branch to GitHub: (git push origin feature).
+
+5. Create a new pull request against `master` branch.
+
+> **Note**, you don't need to take care about typescript compilation and minifycation, there are automated [git hooks](./.husky) taking care of that!
+
+## License
+
+Backporting (BPer) open source project is licensed under the [MIT](./LICENSE) license.

dist/cli/index.js

@@ -29,19 +29,12 @@ runner.run();
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 const commander_1 = __nccwpck_require__(4379);
-const process_1 = __nccwpck_require__(7282);
+const package_json_1 = __nccwpck_require__(6625);
 class CLIArgsParser {
-    constructor() {
-        this.pkg = {
-            name: process_1.env.npm_package_name ?? "backporting",
-            version: process_1.env.npm_package_version ?? "0.0.0",
-            description: process_1.env.npm_package_description ?? ""
-        };
-    }
     getCommand() {
-        return new commander_1.Command(this.pkg.name)
+        return new commander_1.Command(package_json_1.name)
-            .version(this.pkg.version)
+            .version(package_json_1.version)
-            .description(this.pkg.description)
+            .description(package_json_1.description)
             .requiredOption("-tb, --target-branch <branch>", "branch where changes must be backported to.")
             .requiredOption("-pr, --pull-request <pr url>", "pull request url, e.g., https://github.com/lampajr/backporting/pull/1.")
             .option("-d, --dry-run", "if enabled the tool does not create any pull request nor push anything remotely", false)
@@ -16053,6 +16046,14 @@ function suggestSimilar(word, candidates) {
 exports.suggestSimilar = suggestSimilar;
 
 
+/***/ }),
+
+/***/ 6625:
+/***/ ((module) => {
+
+"use strict";
+module.exports = JSON.parse('{"name":"@lampajr/bper","version":"1.0.4","description":"BPer is a tool to execute automatic git backporting.","author":"","license":"MIT","private":false,"main":"./dist/gha/index.js","bin":{"bper":"./dist/cli/index.js"},"files":["dist/cli/index.js"],"scripts":{"prepare":"husky install","clean":"rm -rf ./build ./dist","compile":"tsc -p tsconfig.json && tsc-alias -p tsconfig.json","package":"npm run package:cli && npm run package:gha","package:cli":"ncc build ./build/src/bin/cli.js -o dist/cli","package:gha":"ncc build ./build/src/bin/gha.js -o dist/gha","build":"npm run clean && npm run compile && npm run package","test":"jest","test:report":"npm test -- --coverage --testResultsProcessor=jest-sonar-reporter","lint":"eslint . --ext .ts","lint:fix":"npm run lint -- --fix","ts-node":"ts-node","preversion":"npm install && npm test","postversion":"git push && git push --tags"},"repository":{"type":"git","url":"git+https://github.com/lampajr/backporting.git"},"keywords":["backporting","pull-requests","github-action","cherry-pick"],"bugs":{"url":"https://github.com/lampajr/backporting/issues"},"homepage":"https://github.com/lampajr/backporting#readme","devDependencies":{"@kie/mock-github":"^0.1.2","@types/fs-extra":"^9.0.13","@types/jest":"^29.2.4","@types/node":"^18.11.17","@typescript-eslint/eslint-plugin":"^5.47.0","@typescript-eslint/parser":"^5.47.0","@vercel/ncc":"^0.36.0","eslint":"^8.30.0","husky":"^8.0.2","jest":"^29.3.1","jest-sonar-reporter":"^2.0.0","semver":"^7.3.8","ts-jest":"^29.0.3","ts-node":"^10.8.1","tsc-alias":"^1.8.2","tsconfig-paths":"^4.1.0","typescript":"^4.9.3"},"dependencies":{"@actions/core":"^1.10.0","@octokit/rest":"^19.0.5","@octokit/types":"^8.0.0","@octokit/webhooks-types":"^6.8.0","commander":"^9.3.0","fs-extra":"^11.1.0","simple-git":"^3.15.1"}}');
+
 /***/ }),
 
 /***/ 2020:

src/service/args/cli/cli-args-parser.ts

@@ -1,30 +1,15 @@
 import ArgsParser from "@bp/service/args/args-parser";
 import { Args } from "@bp/service/args/args.types";
 import { Command } from "commander";
-import { env } from "process";
+import { name, version, description } from "@bp/../package.json";
 
-interface PkgInfo {
-  name: string;
-  version: string;
-  description: string;
-}
 
 export default class CLIArgsParser implements ArgsParser {
 
-  private pkg: PkgInfo;
-
-  constructor() {
-    this.pkg = {
-      name: env.npm_package_name ?? "backporting",
-      version: env.npm_package_version ?? "0.0.0",
-      description: env.npm_package_description ?? ""
-    };
-  }
-
   private getCommand(): Command {
-    return new Command(this.pkg.name)
+    return new Command(name)
-      .version(this.pkg.version)
+      .version(version)
-      .description(this.pkg.description)
+      .description(description)
       .requiredOption("-tb, --target-branch <branch>", "branch where changes must be backported to.")
       .requiredOption("-pr, --pull-request <pr url>", "pull request url, e.g., https://github.com/lampajr/backporting/pull/1.")
       .option("-d, --dry-run", "if enabled the tool does not create any pull request nor push anything remotely", false)

tsconfig.json

@@ -43,7 +43,7 @@
     // "types": [],                                      /* Specify type package names to be included without being referenced in a source file. */
     // "allowUmdGlobalAccess": true,                     /* Allow accessing UMD globals from modules. */
     // "moduleSuffixes": [],                             /* List of file name suffixes to search when resolving a module. */
-    // "resolveJsonModule": true,                        /* Enable importing .json files. */
+    "resolveJsonModule": true,                           /* Enable importing .json files. */
     // "noResolve": true,                                /* Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project. */
 
     /* JavaScript Support */