Learn about npm package workflow

[NicolasOmar]

Objective

Obtain information about npm publish workflow, having in mind its source code will be stored in GitHub (which has special integrations with npm) and work on a test project to find best practices for an automated npm package workflow.

---

Description

Having in mind semantic-release complexity as well as releases in Github as well as Npm sites, the best option to have good results (using the proposd gitflow in #6), is to create a test repository with some basic code, deploy such repository in npm and github as well as integrating semantic release to automate releases giving branch version or any alternative achived during learning process.

---

Tasks

• Read needed npm related documentation
• Read Github documentation related to npm integration
• Create test repository
• Create npm package and add needed data
• Copy codebase from Create initial project #5
• Integrate semantic-relaese
• Achieve a patch release in npm and github at same time (as 0.0.2) with semantic-release
• Achieve a minor release in npm and github at same time (as 0.1.0) with semantic-release
• Achieve a major release in npm and github at same time (as 2.0.0) with semantic-release
• Integrate semantic-release Github Action using a .yml file and default configuration
• Achieve custom branching management on semantic-release configuration
• Achieve version sync between package.json, git release and npm version (see specific configuration for that)

---

Ticket relationships

Relationship	Involved tickets
Is child from	none
In parent of	none
Is related to	#5 - #6
Is blocked by	none
It blocks	#9

---

Technical notes

The used links on this investigations are the following:

• Npm registry docs
• Working with GitHub and Npm
• Semantic-release resources
• [Video] First steps by Bayan Bennett
• [Video] Semantic-release by Bayan Bennett
• [Video] Creating a npm package by James Q Quick
• [Video] Creating a npm package by DesignCourse
• [Video] How to implement Semantic Release by Bruno Antunes
• [Video] Automate your GitHub Actions Releases by Dave's Dev Channel

[NicolasOmar]

Understand about npm accounts and organization accounts (based bibliography)

[NicolasOmar]

The used code/repo/package is the following

• Repository
• Package

[NicolasOmar]

After the needed research, I got to the conclusion that GitHub has a separated npm registry where you can publish your own packages on the same repository.
After researching the enough time, I decided to focus on npm only because the benefits (in my case) are none compared to have the package stored in main npm registry.

[NicolasOmar]

Starting to work on a custom gitflow-based config to use it in the main repository

[NicolasOmar]

After some tests related to the .releaserc configuration file. I am coming to the conclusion that could not be possible a strict implementation based on a static configuration rather than documenting a specific and methodic way to write commit/merge comments to structure version changes in the desired way.
Before closing the issue and get into definitive conclusions, I will write a new discussion on semantic-release channel to obtain certain guidence and a better understaing about the tool and its best practices.

[NicolasOmar]

I created a new discussion to understand if my approach was not the correct one and if there is a correct way to achieve what I would like.

[NicolasOmar]

After some investigation regarding semantic-release plugins and the best way of implement them in a selective way to achieve update on package.json, npm published version and Github Release version

Documentation:

• Semantic-release configuration
• Package.json
• GitHub Action used to deploy

[NicolasOmar]

At this stage I will look at simplified gitflows to select a custom version which will fullfil my need for the project

• Gitflow document

[NicolasOmar]

To close the ticket, I want to add some final thoughts about the experience and the best practices regarding automated npm versioning:

• Before starting, check you have installed Node v18 or above because is a requirement from semantic.
• Log into npm on your local machine through cli with npm login and check you logged in with npm whoami (should return your username).
• Install semantic-release following the steps provided by their tutorial.
  • On the install part, just execute the following npm i --save-dev semantic-release @semantic-release/changelog @semantic-release/commit-analyzer @semantic-release/exec @semantic-release/git @semantic-release/github @semantic-release/npm @semantic-release/release-notes-generator
  • That should change your package.json file version to 0.0.0-development. Leave it like that because you will not need to check it anymore.
• To publish your package for the first time, execute npm publish --access public.
  • It should be enough to have your first version publicly available on npm.
• Now, you should create a .relaserc file on your root folder and paste the content from this file.
  • The file is a configuration where semantic-release will only be used on the main branch as well as will use the list of plugins that will execute the following:
    • commit-analyzer: Analyze all commit history from the last release and generate a list to be exported.
    • release-notes-generator: Add a new release note for the next version to be published.
    • changelog: Create or update the CHANGELOG.md (like this one) file with the previously formatted commits for the next version to be published.
    • github: Create a new git-tag and release for the package's repository. (example)
    • npm: Create a new version for the package in its npm site. (example)
    • git: Update the package.json version to the new one. (example)
• Also, you should create a file to run the process mentioned above on GitHub Action (I used that CI) in a new set of folders (.github -> workflow -> node.js.yml) on your project's root and paste the content from this file
  • The file should be in a location like this one .github/workflows/node.js.yml.

After executing the steps above, you should be able to commit the changes from your new files, commit them with a comment like fix(): adding new files for automated version deploy process and push in main.

That action will run the semantic-release process following the plugin list you provided, updating your Github release and tag, your published version on npm, and synchronizing the version number on your package.json file.

To understand which will be the gitflow I will implement, please go to the related document.

Also above, there are the links of the used repository and package for these experiments.

[NicolasOmar]

Post-issue: Adding another article to publish a npm package in a simplified way