zdp-ui-usama v0.2.0

ZDP UI Service

How to use npm package in ZDP apps

1. Create a .npmrc file at the root directory of your project
2. Paste the following in the .npmrc file:

@zdp-pim:registry=https://pkgs.dev.azure.com/ZDP-DEV/ZDP-PIM/_packaging/npmpackages/npm/registry/ 
registry=https://registry.npmjs.org/                                
always-auth=true

"Please be advised that the default behavior of the 'npm install' or 'npm i' command is to fetch packages from the public npm registry located at https://registry.npmjs.org/. 
However, if the intention is to retrieve packages from a private registry, a necessary step involves the creation of an '.npmrc' configuration file.This '.npmrc' file should 
include the URL of the designated private registry. Additionally, it is essential to retain access to the public registry by ensuring that its URL is also included within the 
'.npmrc' configuration.This ensures the availability of packages hosted on the public registry alongside those from the private registry. 

3. To generate an access token for private registry access, follow these steps:

   Execute the following commands in order: Run in the terminal npm i -g vsts-npm-auth Now, run in the terminal vsts-npm-auth -config .npmrc A web browser window will open automatically to authenticate you using your Zones ID.

4. Now, simply run npm i/ npm install all the packages will be downloaded which are present in package.json

5. If you are not aware of the latest package to put in your package.json simply run npm install @zdp-pim/zdp-ui-kit

Setup the project - Extend/create npm package:

1. Clone UI service repo with git clone https://ZDP-DEV@dev.azure.com/ZDP-DEV/ZDP-PIM/_git/ZDP-UI.
2. Create a .npmrc file at the root directory of your project, if not present
3. Paste the following in the .npmrc file:

@zdp-pim:registry=https://pkgs.dev.azure.com/ZDP-DEV/ZDP-PIM/_packaging/npmpackages/npm/registry/ 
registry=https://registry.npmjs.org/                                
always-auth=true

4. Run in the terminal npm i -g vsts-npm-auth
5. Now, run in the terminal vsts-npm-auth -config .npmrc
6. If you get any error about command not found or recognizable then please troubleshoot npm setup in your environment by going through Troubleshoot Or you can also try with npx vsts-npm-auth -config .npmrc
7. On success, it will display the path where .npmrc was created and if it does not display the path then it would be C:\Users\<user-name>\.npmrc (Replace with your actual username)
8. Go to the path where .npmrc was created and open the file. The path will look like C:\Users\.npmrc
9. This step is optional if you want to keep the token global rather than local to the project directory. Copy the content of file generated in previous steps to this file.
10. This step is also optional if you choose to keep the token global. Open a terminal or command prompt and run the following command to set the token as an export variable:

For Linux/macOS: export NPM_TOKEN=YOUR_AUTH_TOKEN

For Windows (Command Prompt): set NPM_TOKEN=YOUR_AUTH_TOKEN

For Windows (PowerShell): $env:NPM_TOKEN="YOUR_AUTH_TOKEN"

Replace YOUR_AUTH_TOKEN with the actual value of your authentication token.

11. This step is also option if you want to keep the token global. Add the above command to ~/.bashrc, ~/.zshrc or add Path Environment variable according to the respective Operating System
12. Run npm install

When extending the functionality of the cloned npm package, the .npmrc file, essential for registry configuration, is automatically included. Prior to pushing changes, local testing is crucial. 
Create a dedicated branch for your work, and after thorough testing, generate a Pull Request (PR) with a commit message as mentioned below.' Upon PR approval and merge into the development branch, 
Azure Artifacts will increment the package's version number, facilitating version control and tracking. 

##Publishing an Article with Semantic Versioning and Commit Guidelines

To streamline the process of publishing articles and maintaining version consistency, we've implemented Semantic Release and specific commit message guidelines for the zdp-ui project. Follow these steps to ensure a smooth release cycle:

Prerequisites

A properly generated .npmrc file, as outlined in the earlier steps.

Commit Guidelines

###Commit Message Pattern:

When committing changes, adhere to the following commit message patterns:

###perf: for performance-related changes. ###feat: for new feature additions. ###fix: for bug fixes.

It's important to use these prefixes since Semantic Release relies on the feat or fix prefix in the latest commit to calculate the next package version.

###Versioning Insights:

Semantic Release automatically increments version numbers based on the commit message prefixes:

###fix: increments the patch number. Example: From version 1.0.0, the update becomes 1.0.1.

###feat: increments the minor number. Example: From version 1.0.1, the update becomes 1.1.0.

For major changes that introduce breaking changes, follow the next step.

###Breaking Changes:

For major changes that include breaking changes, you must include a "BREAKING CHANGE:" or "BREAKING CHANGES:" footer. This informs Semantic Release to increment the major version number.

###Example:

feat: Adding a new feature

BREAKING CHANGES: This new feature alters the existing API.

###Commit Message Examples Fix Example:

fix: Correcting a critical rendering issue

###Feature Example:

feat: Introducing a dark mode option

###Breaking Change Example with Footer:

fix: Updating patch number and it is a breaking change

BREAKING CHANGES: Added a patch that is very important...

###Breaking Change Example without Footer:

fix: Introducing a significant new feature that breaks existing functionality

BREAKING CHANGE: New feature XYZ affects the existing API flow.

###Automated Publishing

Remember that you don't need to explicitly publish the article; the Azure Pipeline is configured to handle the building and publishing process automatically upon mergein dev. This ensures that the published content aligns with the latest version of the project.

By following these guidelines, you contribute to the consistency of versioning, the accuracy of commit messages, and the overall efficiency of the publishing process. For further information about Semantic Release and versioning strategies, refer to Semantic Release versioning.

##Add in your Pipeline 1. firstdownload .npmrc file from the library, place the following task under step: "inside .azure-pipelines/templates/steps/steps-template.yml"

- task: DownloadSecureFile@1
  displayName: "download-npm-rc"
  name: "npmrcFileReference"
    inputs:
      secureFile: .npmrc  

2. Then you have to add a bash script before npm start the bashscript is as follows.

- task: Bash@3
  displayName: "Copy npmrc to repo path and set permissions"
  inputs:
      targetType: "inline"
      script: |
        file=$(npmrcFileReference.secureFilePath)
        sudo chown root:root $file
        sudo chmod a+r $file
        sudo cp $file $(Build.Repository.LocalPath)```

###For refrence you can check ZDP-ADMIN-UI/ZDP-PIM-UI pipeline