Package-V simplifies the management and versioning of NPM packages by automating the publishing process to the GitHub Registry. When a pull request is merged, Package-V automatically handles version increments based on the type of changes (minor, major, or breaking) and updates the package.json.

By delegating version management and package publishing to Package-V, you save time and reduce the risk of human error, ensuring a smooth and efficient workflow for your NPM projects.

Getting Started Guide

Provide step-by-step instructions on how to install and set up Package-V in a GitHub repository.

1. Installation:

   Navigate to the GitHub App's Installation Page

   Go to the GitHub Marketplace or directly to the GitHub App's page. If you are looking for Package-V:

   • Visit the GitHub App page link: Package V.
   Click on the "Install" Button

   Once you’re on the GitHub App page, you’ll see an "Install" button in the upper-right corner. Click this button to start the installation process.

   Choose Installation Scope

   You will now be prompted to choose where you want to install the app:

   • For a Single Repository: If you only want to install the app on one repository, select this option. You will be able to choose the specific repository from your list.
   • For an Organization or All Repositories: If you want to install the app across all repositories within an organization or for all your personal repositories, select this option. You can choose either specific repositories or allow the app to access all repositories.
   Review Permissions

   Before finalizing the installation, GitHub will display the permissions the app is requesting. For Package-V, this might include permissions to:

   • Read and write access to repositories (to manage package.json).
   • Read access to pull requests (to track merges and updates).
   • Write access to packages (to publish NPM packages).Make sure the permissions align with what the app needs and click "Approve".
   Confirm and Install

   After reviewing permissions, confirm the installation by clicking the "Install" or "Authorize" button. This will complete the installation process.

   Configuration (If Applicable)

   Once installed, some GitHub Apps may have additional configuration steps. For Package-V:

   • Ensure your package.json follows the correct naming format (@username/package-name or @organization/package-name).
   • Check that your branch naming conventions (e.g., fix/, feature/, !feat/) are in place to enable automatic versioning.
   Start Using the GitHub App

   Now that the GitHub App is installed, it’s ready to use! For Package-V, it will automatically manage versioning and publishing once you start merging pull requests into your specified branches (development, QA, or main).

Version management

The initial version is determined by the version specified in the package.json file when the package is created. Subsequent versions are automatically updated based on the branch prefix of the merged PR. Supported branch prefixes and their effects are:

• fix/bugfix/bug: Increments the patch version (1.0.x).

  Example: fix/principal-title → Version updates from 1.0.0 to 1.0.1.

• !feature/!epic/!feat/breaking_news: Increments the major version (x.0.0) and resets the minor and patch digits to zero.

  Example: !feature/login-refactor → Version updates from 1.2.3 to 2.0.0.

• All other prefixes: Increments the minor version (1.x.0).

  Example: feature/login → Version updates from 1.1.0 to 1.2.0.

Alpha and beta versions:

When a PR is closed and the base branch in this one is different to a develop ("develop", "dev", "development"), qa (qa) and main ("main", "master") branch name, is going to added to the package version a sufix call "alpha".

Example:

PR: feature/login <- fix/title

current package version: 1.2.0

Next package version: 1.2.1-alpha

A similar behaviour will happens when a when a PR be closed in the ("develop", "dev", "development"), qa (qa) branches; the sufix that is oging to be added is going to be "beta":

Example:

PR: develop <- feature/login

current package version: 1.2.1

Next package version: 1.3.0-beta

Advanced Options

Skipping Package-V Execution

If you want to skip the automatic versioning and publishing process for a specific pull request, simply add the label:

Label: packagev:skip

This ensures that the version update and publishing process are bypassed when the pull request is merged.

Customizing the Package Version

If you want to set a custom version for the release, use the following label in the pull request:

Label: packagev:x.x.x

For example, to set the version to 1.2.3, add the label: packagev:1.2.3. This allows you to define a custom version number when the PR is merged.

Publishing

The package is published automatically when a Pull Request is merged.

Finally, when a PR is closed and the base branch is qa and the headed branch is develop ("develop", "dev", "development"), the version of the package is going to keep the same.

Example:

PR: qa <- develop

current package version: 1.3.0-beta

Next package version: 1.3.0-beta

In addition, similar behaviour is done when a PR is closed in the main (main or master) branch, if this is the base branch, all sufixes in the version will be removed and the merged version will be kept without modification to publish this one to be used in production.

Example:

PR: main <- qa

current package version: 1.3.0-beta

Next package version: 1.3.0

Considerations

• Package Name: The name in the package.json must follow this format:
  • User: @[username]/package-name
  • Organization: @[organization]/package-name

Limitations

• Only one package can be handled per repository.
• Works exclusively with GitHub repositories.

Uninstalling or Managing the GitHub App

If you ever need to uninstall or manage the app (e.g., change the repositories it has access to):

1. Go to Settings (for your personal account or organization).
2. In the "Integrations" or "Installed GitHub Apps" section, locate the installed app.
3. Click "Configure" to adjust its permissions or uninstall it.