added GitHub workflow to publish to NPM's public registry

[TysonMN]

Resolves #20

This PR adds a GitHub workflow to automate the publishing to NPM's public registry.

I copied this template, and then made the following modifications.

• Added three links to documentation.
• Changed the value of node-version from 10.0.0 to 12.0.0 (since it seems like a good idea to use a newer version).
• Changed the value of workspace from "." to ".codedoc" (since this value gives the path to the package.json file).

How this works:

• Executed when the master branch contains a commit with a message that matches the pattern given by the value of commit_pattern. An example is Release 1.2.3.
• Creates a tag with a name and message matching the patterns respectively given by the values of tag_name and tag_message. Continuing the previous example, the name and message would both be v1.2.3.
• Publishes to NPM's public registry.

You have to do one thing on your end, which is to create a new GitHub secret with the name NPM_AUTH_TOKEN and with a value of a personal authentication token for your account on npmjs.com.

[loreanvictor]

ok the only issue I can see with this gh-action (which is pretty nice btw):

• we should at some step also run npm build before npm publish (I do apologize I suspect I failed to mention that in the original issue)
• isn't this line wrong? I mean we don't want to publish the contents of .codedoc folder but rather the root folder.

[TysonMN]

• we should at some step also run npm build before npm publish (I do apologize I suspect I failed to mention that in the original issue)

Good to know. No worries if you forgot.

Can you try and remember all the commands you execute in order to publish a new version of this plugin? Is it just npm build followed by npm publish? Do they need to be executed in a certain directory? (My guess is that they need to be executed in the .codedoc directory.)

• isn't this line wrong? I mean we don't want to publish the contents of .codedoc folder but rather the root folder.

It certainly could be. I haven't tested this.

The documentation for the workspace key says

custom workspace directory that contains the package.json file

I interpreted that to me the relative path to the directory that contains the package.json file, but I could be wrong about that.

More generally though, my impression of the root directory of the coding-blog-plugin repository is that it is foremost a CODEDOC site containing the documentation of the CODEDOC plugin of the same name (i.e. coding-blog-plugin) but also contains the code for the plugin. That also makes me think that this build script needs to be given .codedoc instead of ..

Publishing the root directory of this repository makes me thing that the published artifact would also contain all the CODEDOC files used to create the documentation website.

What exactly gets published by npm publish?

I can answer this question for .NET and NuGet packages. When building Elmish.WPF, this line causes a NuGet package to be created. Then the act of "publishing" Elmish.WPF is merely uploading this file to https://www.nuget.org/packages/Elmish.WPF.

[loreanvictor]

Well in this case, the whole project is a Node package (hence there is a package.json in the root of the project), but also .codedoc is independently a Node package (and has its own package.json file). The reason for this is that non-NPM (or non Javascript) projects can also utilize CODEDOC, and even in case of NPM projects using codedoc dependencies of the project differ from those of CODEDOC.

Publishing the root directory of this repository makes me thing that the published artifact would also contain all the CODEDOC files used to create the documentation website.

nope, only files and folders specified here will be published (alongside some defaults like the package.json itself, README, so on). as you can see, none of them are actually present in the repository (thats why npm run build should happen before npm publish so that the files that are going to be published are built).

[TysonMN]

...hence there is a package.json in the root of the project...

Oh! I didn't even notice that.

• isn't this line wrong? I mean we don't want to publish the contents of .codedoc folder but rather the root folder.

I agree with you now. Thanks for being so patient with me. I pushed a change to have the workspace be the root directory.

• we should at some step also run npm build before npm publish

How do we do that?

[loreanvictor]

How do we do that?

I suspect adding a step before "Publish if version has been updated" should do the trick, perhaps a step like this:

    - name: build the package
      run: npm run build

Thanks for being so patient with me.

No need to thank me, it would be actually weird if I just expected everyone to know all about how NPM works (or some other technology / framework / library / language / etc works) on an open-source project, specifically considering that I learned a lot of these stuff about NPM max 2 years ago myself (and still learning by the day) ;-)

[TysonMN]

Ok. Added that build step.

Testing seems a bit annoying. I think npm-publish-action doesn't supports publishing to a custom (testing) registry and GitHub actions do not directly support being manually triggered (though there seems to be a workaround).

Since this work isn't so critical, maybe we just wait and test next time there is a new version to published.

Want to complete this PR then?

[loreanvictor]

yes seems like the best way to move forward. thanks for the awesome addition!

[loreanvictor]

ok so this is failing atm and causing our commits to be invalidated. as a result, I am going to comment out the steps for now until I can setup some testing protocol for this first (perhaps using this tool or similar tools).

[TysonMN]

Ah. Sorry that it didn't work straightaway. I see the failure, am testing locally, and am getting similar failures.

I don't know what you mean by

...causing our commits to be invalidated.

[loreanvictor]

Sorry that it didn't work straightaway.

No worries that was expected, what wasn't expected was the amount of emails and alerts that GitHub fires for failing actions.
And by "invalidated" I mean GitHub simply marks the commit as "some checks failed" with a red cross. I commented the action out for now because this is the same signal that you would get if for example the docs aren't updated (the other action fails) or some CI process fails (which we currently don't have any), so the signal is actually important and shouldn't be cluttered (alongside panicy emails from GitHub, which again clutters the signal on when something IS truly wrong).