Automatic GitHub releases and minor quality of life updates

[AleixMT]

With these changes I wanted to give the users the freedom of automating the process of installation using the terminal, either by cloning the repository, building the extension and installing it or by downloading and installing the latest release. I also added some minor quality of life updates in the repository.

The justification and explanation for each feature is the following:

Justification of changes for automating the build process

If you want to automate the building process by:

git clone https://github.com/ininavicode/arm-syntax-vscode-extension
cd arm-syntax-vscode-extension
vsce package

You will find the following error:

 ERROR  The specified icon 'extension/images/logo.png' wasn't found in the extension.

Obviously, this is because the logo is missing in the repo. I simply added it on the fork, so the previous commands can work correctly.

I also removed the rule in the .gitignore that ignores the path images/, since the image was expected to be in this path.

I am guessing that because the logo is a binary file and not a text file you (reasonably) wanted to ignore it, but since the logo is a build dependency, I think this is a clear exception and must be included in the repository to allow this behaviour.

Justification of changes for automating the download process

I tried automating the installation process by:

wget https://somelink.com/arm-syntax-vscode-extension-latest-version.vsix  # Direct dynamic link to vsix with latest changes
code --install-extension arm-syntax-vscode-extension-latest-version.vsix

But I was not able to find a direct dynamic link to the installable latest version of the extension. This is a URL (or something that provides information to generate that URL) that points to a .vsix installable package of the extension built with the latest changes in the code.

Anyway, by using GitHub releases we can get this type of service for free by building the .vsix package automatically in GitHub servers with a GitHub Actions workflow triggered on each push in the main branch and afterwards publishing it as a release with the version specified on package.json, in the version field.

In the fork, the worklow is configured to update releases with the same version number:

• To create new releases, update the version number in package.json and push the changes to the main branch and the workflow will automatically make a new release.
• To update existing releases, use the version number of the release that you want to update in package.json and push a commit to the main branch and the workflow will update that release.

Due to the previous, users can do the following to achieve the idea of the previous snippet:

LATEST_VERSION=$(curl -s https://api.github.com/repos/ininavicode/arm-syntax-vscode-extension/releases/latest | grep "tag_name" | cut -d '"' -f 4)
LATEST_VERSION=${VERSION:1}
wget -O arm-syntax-vscode-extension.vsix \
  https://github.com/ininavicode/arm-syntax-vscode-extension/releases/download/v${LATEST_VERSION}/arm-syntax-vscode-extension-${LATEST_VERSION}.vsix  # Download latest release
code --install-extension arm-syntax-vscode-extension.vsix  # Install extension

Minor changes

• Added makefile with targets arm-syntax-vscode-extension.vsix or no options for conditional build, clean to remove build, conditional install to install extension and conditional uninstall to uninstall extension.
• Added in the README.md commands to build extension, to install extension from terminal, to install requirements, a badge to show number of downloads in VSCode marketplace that links to the marketplace entry of the extension, build requirements with fancy badges, added Estructura de Sistemes Operatius and Fonaments de Computadors to the "adapted for" enumeration in the Features section.
• Added makefile and .github/ to .vscodeignore.
• gitignored .vsix files.

Workflow considerations

To make the workflow work, (in addition to merging this pull request) you will need to activate GitHub Actions in this repository.

You will also need to provide a token to it in order to authorize the creation of releases by the workflow. You may do so by creating a new repository secret called GH_TOKEN. Inside this secret you need to paste a classic personal access token with all the "repo" permissions checked. You can create it from the developer settings in the settings on your GitHub profile.

I tested the code extensively, but if you detect errors let me know by requesting changes and I will address them in further commits.

Thank you for creating this wonderful piece of software that I am currently incorporating into my stack.

[AleixMT]

Hello again, you merged the changes, but I think that you did not add the authentication token (correct me if I am wrong).

Without the token my functionality will not work and no releases will be automatically made:

:--:
Notice the presence of a ✓ in the last commit of my fork, which created the release 0.0.5 automatically, while there is a ❌ in yours, meaning that the last workflow to automatically make a release failed. Also, you do not have any release as the fork does.

If we inspect the last workflow run of your repo we can see the following error:

This probably means that the authentication token was not supplied to the workflow, which resulted in error and no release published automatically.

I will explain how to add the token step by step and trigger the first release in order to make the automatic installation work.

1. Generate a new classic token marking all the repo permissions in your profile settings https://github.com/settings/tokens/new. I recommend setting no expiration date to minimize down-time and maintainance. You can always delete the token from this screen. You can call the token "arm-syntax" for example, as I show in the image. Click in the bottom button labeled "Generate token".
   
2. Copy the token. Once you leave the page you will not be able to see the token again. The token can be used to authenticate against your account so you must treat it as a password (it's a secret, don't share it).
3. Create a new action secret in your repo. You should be able to do it from this URL: https://github.com/ininavicode/arm-syntax-vscode-extension/settings/secrets/actions. The name must be GH_TOKEN and the secret is the personal access token that you copied in the previous step. Click on the button at the bottom labeled "Add secret":
   
4. Finally, you need to create and upload a new commit on branch master. I suggest that you do an empty commit (but any commit pushed into master will work):

git checkout master
git pull origin master   
git commit -am "empty commit to trigger workflow" --allow-empty
git push origin master

5. Finally, you will see the status of the workflow in here https://github.com/ininavicode/arm-syntax-vscode-extension/actions. If I have done my job properly, the next workflow should exit with a correct status (✓) and a release should have been made in your repository automatically. You will be able to see it in here: https://github.com/ininavicode/arm-syntax-vscode-extension/releases

Thank you for your collaboration.

[AleixMT]

@ininavicode

[AleixMT]

Hi there @ininavicode ,

Sorry to bother you again, but the workflow failed because it does not have permission to write the release to the repo.

To give write permissions you need to go here (settings of the repo, then actions menu):
https://github.com/ininavicode/arm-syntax-vscode-extension/settings/actions

And select write and read permissions for the workflow.

I hope that with this change we can finally have this working 👯

Thank you for keeping up the great work.

[AleixMT]

... afterwards do another empty commit to trigger the workflow and make the first release. Currently there are no releases available yet: