-
Notifications
You must be signed in to change notification settings - Fork 1
Home
Firstly you will need to create an account on err0 and create an organization and its “space”. The space will allow you to bundle individual projects (git repositories) into a software product and finally publish this software’s error codes and associated information to a knowledge base micro-site which you can filter and share with your collaborators inside and outside of your organization. Start here: https://login.err0.io/ to create your account. After creating your organization you will be sent to the getting started guide, there’s more information there and we suggest you read it carefully, we’ve shortened the steps here to get you started quickly.
In your space you will need to create a “numbering policy” and then a “project” for your first git repository. Note that each repo will need its own project, and this applies to git submodules. It is easiest to work with submodules if these are cloned individually as top level git projects, however we can help you change the way our scripts work so that they work with your submodule hierarchy from the top level git project. Click on your newly created numbering policy to see the options in the right hand side-bar.
The “numbering policy” contains “error detection settings”. By default we collect local comments, a method signature and the line of code on which the error code is inserted; however we find err0 more useful with a few lines of code as context before and after the error code - so you can enable this in our “Error detection settings” if you wish.
Once a policy is in place it is time to create a “project” for your git repo. You can do this on the projects page. It is almost always certain that your working directory will contain build artifacts - dependencies, build output - you will need to set up included and excluded directories and files in the project’s “agent settings”. Note that “included directories” starts off with “.” e.g. the root of your git repository and it will process all files under this root. These options are in the project’s side-bar.
With that said, it is time to create an “agent API token” for err0agent and download the scripts. This is done on the projects page, you will find this towards the bottom of the right hand side-bar. Add an agent token and click on the robot icon to access these downloads. Choose your operating system, we support Linux, MacOS and Windows; err0agent is distributed via docker so you will need that installed as well.
To insert the codes run the script “sh err0-insert.sh” (Windows: “err0-insert.bat”).
You can view your codes with “git diff” and also on our “error codes” page. Here you can search and filter the codes, and define knowledge base entries, severity and priority and also tag your codes.
It’s likely that the first time around you get more error codes inserted than you need. As such your project starts off in sandbox mode. If you’re unhappy with the changes that err0 makes, just run “git checkout -f” to start again, until you are happy. But don’t commit this! Clean your directory again with “git checkout -f” and “Change to production mode” first. This is at the bottom of the project side-bar.
Great! You’re ready to commit changes. So run “sh err0-insert.sh” again for the first codes and commit this to your git repo. At this point we have gathered information about your branches and tags in err0 and there’s another set-up step to do before you’re ready.
By default “master” and “main” are considered commit (production) branches. On the project side-bar there is a section called “error numbers finalization”. In fact, we mark error codes as committed after the “err0-check” script is run and only on a “commit branch”. Committed error codes are considered ready to publish as “software” via a knowledge base micro-site. So, when you’re ready, you can run “err0-check” script on this branch. Perhaps you want to mark your current branch as a commit branch this first time around and change this setting later.
You can run “err0-check” via build automation on any branch, it will fail the build if an error code needs to be added or changed and pass the build if the error codes in your software are canonical. We use this on our development and production branches.
This brings us onto the topic of software & versions. It may be that your project is fully contained in just one git repository & associated err0 project. But many software products are composed of different components in different git repositories so first we need to define the software products to publish and specify which “err0-check” run corresponds to the release version of your software. You’re probably not ready to release yet - don’t worry you can update the version to a released version later.
On the software page, click add software. Be sure to ensure that the visibility is “Private”. “Public” visibility software can be viewed on your space without a user being a member of your organization. This makes sense for open source projects. Choosing to enable semantic versioning will enforce semver rules on the version number. Disable this if your version numbering (think git tags for releases) doesn’t match this.
Once the software is added you can define its first version. There is a link in the sidebar on the software page or just go straight to the versions page to define the first version. If you skipped the section above about “error numbers finalization” you should go back and go through those steps - you only see “commit” runs of “err0-check” in the dialog. Build the bundle with the component or components you need and this defines a software version.
The final step to get you started is to publish via a knowledge base. The knowledge base section allows you to define micro-sites for each software that you publish. These start off in draft mode (only err0 users can access) and can have a password. There are more options on the side-bar for a knowledge base. For example you can filter what you publish by version and/or tag. You can publish many knowledge bases for the same software but different audiences. Once you’re happy that your draft knowledge base shows what you want you can click to “publish knowledge base” also in the side-bar.
You can also grant access to your “space” to other users. The free tier starts off with 3 users. To grant the same access to another user as you have initially you will need to grant three roles - “Owner”, “Security Manager” and “Error Master”. Speak with us for more information about roles, any other questions and to upgrade to a paid plan.
See also: