Creating Tags and Releases using NPM

In this week's challenge we made a release of the static-site-generator that I've been working on throughout the semester. As we go along the process, I will most likely provide additional information, as I made many mistakes and learned many things about the process. However, this is not an alert to go crazy and think the world will be on fire - the process was relatively easy.

Step 1: NPM

As we are using NPM to publish our package, it would make sense to head over to the NPM website and create an account. Ensure you pick a good password, because the last thing you want is your development products to be hacked into.

⚠️ IMPORTANT!

Make sure you go over to your email that you provided and verify it. You will not be able to publish anything without clicking the one button in the email.

Step 2: Login to your NPM Account

Simply go to the terminal in which you are writing your code that you would like to publish, and type in npm login. You will be prompted for your username, password, and email. Use an appropriate email for the public.

Step 3: Package.json

If you have not already done so, create a package.json by using npm init. You don't lose anything by running it again, and I would recommend you do this step to update anything in the package.json file, such as the package name. At this point, I would also head over to the NPM website, and search through packages for a potential name. You can't use a name that has already been used (You will get the error in the next step).

Step 4: Publishing your package

Now that you have created your package.json and pushed it into the main branch that you are going to be releasing. You can pass along npm publish in the cli. Here are some errors that MAY come up:

❌ Potential Error:

npm ERR! code E403
npm ERR! 403 403 Forbidden - PUT https://registry.npmjs.org/sitegenerator - Package name too similar to existing package site-generator; try renaming your package to '@nlbndn/sitegenerator' and publishpm publish --access=public' instead
npm ERR! 403 In most cases, you or one of your dependencies are requesting
npm ERR! 403 a package version that is forbidden by your security policy, or
npm ERR! 403 on a server you do not have access to.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\ASDF\AppData\Local\npm-cache\_logs\2021-11-27T01_32_54_483Z-debug.log

This means that your package name is already taken, and you need to rename it.

💡 Go to the package.json file and rewrite the key value to the "name".

❌ Potential Error

npm ERR! code E403
npm ERR! 403 403 Forbidden - PUT https://registry.npmjs.org/sitegen - You do not have permission to publish "sitegen". Are you logged in as the correct user?
npm ERR! 403 In most cases, you or one of your dependencies are requesting
npm ERR! 403 a package version that is forbidden by your security policy, or
npm ERR! 403 on a server you do not have access to.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\ASDF\AppData\Local\npm-cache\_logs\2021-11-27T01_33_19_501Z-debug.log

This means that you are not authorized to publish packages. Remember how I said to verify your email?

💡 Go back to step 1 and ensure you verify your email!

✅ the correct output will look like this at the end:

npm notice === Tarball Details ===
npm notice name:          nlb-ssg
npm notice version:       1.0.0
npm notice filename:      nlb-ssg-1.0.0.tgz
npm notice package size:  114.9 kB
npm notice unpacked size: 306.0 kB
npm notice shasum:        3c043be5e7f92b4d0aea72f2535825bbedc85a47
npm notice integrity:     sha512-hiAycOWIxmBh2[...]U9mgN9lTKv94g==
npm notice total files:   29
npm notice

+ nlb-ssg@1.0.0

Step 5: Creating, Deleting, Committing, Pushing Tags.

(Literally Everything about tags....)

Now that you've published your package, you should see it on the NPM site. To create proper releases, we should use tags. Tags are essentially used to mark certain points in the repositories history which are significant, such as releases, patches, or new versions.

If you are generally good at understanding documentation, here is the documentation for tags.

Creating tags:

To create a tag with the name "v1.0.0" simply use

git tag v1.0.0

If you choose to use annotated tags, they will provide more information such as the tagger name, email and date. You will also include a tagging message and the creation of this is verified too!

Here we create a tag with the message, "first release"
git tag -a v1.0.0 -m "first release"

View all tags:

git tag

View information about a certain tag:

git show v1.0.0

Committing and pushing a tag (Probably the most unclear in the documentation)

git push origin v1.0.0

Committing and pushing ALL tags ( I made lots of typos, and was confused at this point... hence I have added the delete tag section below in case you end up really lost like I was and create 4 extra tags and wonder why they're not showing up in GitHub 😂)

git push origin --tags

Deleting a tag

git tag -d v1.0.0

Deleting a tag that was already committed

git tag -d v1.0.0

git push origin :refs/tags/v1.0.0

.... I think that's about all of the tag commands.

Step 6: Creating a release

Head over to your GitHub Repository, and on the left side of the repository you will see "Releases" right under the "About "section. Once you click on this, you will see you can "Draft a new release".

From here on out, it's going to be simple.

Choose the tag you would like to associate the release with.
Ensure you are releasing the correct branch. Some reasons this can vary may be that you have a develop branch where all development occurs, and a master branch which is the branch that is released.
Write the release title. Make it something short but sweet.
If this is a pre-release (see below), ensure you tick off the box.
Hit "Publish Release".

Pre-release is really helpful for drafting up release notes, and then gathering up a team to help test on stage before releasing development to dev. The pre-release can be used as a guideline to go through and test the features on your application alongside your testing documentation.

Step 7: Creating new releases or patching an old release

I had Reza try and test out my release. Fortunately my documentation was well done and he was able to install it successfully, but I had thrown in some code previously to avoid having so many code blocks with no returns. He told me to run the application locally and see what happened, and behold - my first bug in release. (We take mistakes as opportunities to learn more here, I make way too many to take these negatively, and I learn way more when I fix them).

So I fixed this bug - and made a commit. I did everything I needed to do, but in the wrong order - so here is the way you should do it:

Create a fix for your bug/new code.
Commit the patch/code and push it.
Create a new tag - AND update the version in the package.json accordingly*
Run npm i. This step is not required, but will ensure that any packages that were updated due to a commit made previously will be included.
Commit the new release version AND the tag together. Remember tags signify a change in the codebase that we want to "bookmark" so we can refer back to, as needed.
Push the changes on GitHub.
Create the new release on GitHub.
Go back to the editor and you have to run npm publish again. If you run into errors about not being able to publish again, ensure you changed the version in the package.json to something different.

Accordingly implies to whichever versioning methods your team has decided, i.e. Semantic. I suggest you explore them and even look into having regular releases, perhaps a release schedule.

Step 8: You're done -

If you found this post helpful, I would suggest you write notes for yourself about the process. There are many errors that I ran into, and hence I made this one very informational. Every production team has a release process and this information will be useful again one day when I am 4 tags in, and none are showing up on GitHub.