It is possible to build a Mapeo configuration file using GitHub Actions. This requires setting up your custom configuration directory as a repository on Github.com, adding a /.github/workflows/build.yml script to your repository, and committing changes to that repository.
If you haven't already used GitHub, you may want to study the basics of how GitHub works before proceeding.
Note that since this process relies on using github.com, that you will need internet access to run the build action and download the .mapeosettings configuration file. Hence, unlike building a configuration Via the command line, this process will not work in an offline context.
The first step will be to set up your configuration as a repository on github.com, with the requisite build script files that will trigger a GitHub Actions Workflow to generate your .mapeosettings file. There are a few ways to do this.
If you do not have your own custom configuration already, and are starting from scratch:
You can fork or upload either the Mapeo Default Configuration or the Empty Mapeo Configuration template to your own GitHub account. The choice you make will depend on how you will go about creating your own configuration, as detailed in Planeando la configuración y la estructura de datos.
Make sure that you have the .github/workflows directory in your configuration repository.
If you already have your own custom configuration:
Create a repository on GitHub for your custom configuration.
Commit your existing configuration content to the repository.
Download either the Mapeo Default Configuration or the Empty Mapeo Configuration, and copy over the .github directory to the root directory of your custom configuration.
Commit these files to your repository on Github.com. (Github may ask you for additional permissions to add these files, by confirming via the browser.)
NOTE: Depending on your operating system and setup, it is possible that you do not see a .github/ directory anywhere. You may need to enable viewing hidden files in your system file manager.
On MacOS, you can do so by pressing Command + Shift + . (period) in your Finder window.
Navigate to the Actions screen, and Click "I understand my workflows, go ahead and enable them."
This will bring you to a view of your Workflows. You should see a message "There are no workflow runs yet" if you just enabled Workflows for the first time. You are now ready to start building .mapeoconfig files.
Once you have enabled Action Workflows on your configuration repository, GitHub will generate a Workflow to build a new version of your configuration every single time that you commit a change to your repository.
Once you have committed a change to your repository, and navigate to the Actions tab, you should see your commit message listed as a workflow.
You can click on your commit message to find out more about the status of your build. For example, if your build has encountered an error, there will be a log that can give you an idea of what went wrong. You can commit a change to fix the error, and return to the Actions screen to see if a new Workflow successfully bypasses the problem.
This is the same log that you would see when building a configuration Via the command line.
By opening the Workflow with your commit message, you can also download a .zip file of your configuration, which includes a temporary .mapeosettings file. This is helpful for testing out your configuration before building a versioned file to distribute to users, as described in Probando e iterando.
The Mapeo GitHub Actions Workflow is set up to dynamically bump the version of your configuration per each workflow. It does so using conventional commit messaging of adding feat:, fix:, or chore: before your commit message. For example, if you have a configuration with version 1.1.0, the specific version bumps are as follows:
feat: this will increase your version to 1.2.0. This commit prefix could be used for major configuration updates.
fix: this will increase your version to 1.1.1. This commit prefix could be used for small updates like changing an icon, or adding a field to a category.
chore: this will not increase your version. This commit prefix could be used for correcting typos or fixing errors.
To see a few examples of configuration conventional commit messaging, see the screenshot above in #how-it-works, or check out the commit history on the Mapeo Default Configuration repository.
You can also manually update the first number in your 1.1.0 version in your package.json file, but Digital Democracy's convention is to only do so to indicate breaking changes. That said, you are free to choose a versioning convention that makes the most sense to you.
Once you are done making changes, have tested your configuration using a temporary .mapeosettings file (as described in #how-it-works) and in accordance to the process described in Probando e iterando, you can generate a versioned release of your configuration. The way to do so is as follows:
Navigate to the Actions tab for your GitHub repository. You should see all of your Workflows again.
On the left sidebar, click on the Build & Release link.
You should now see a box with the text "This workflow has a workflow_dispatch event trigger" and a button Run workflow. Click the button, and then click Run workflow again in the popup that will appear.
Doing so will trigger another Workflow titled "Build and Release."
Click on the release to download the versioned .mapeosettings file.
a circular check indicates that the build has completed successfully.
a yellow circle indicates that the build is in process.
a red circle with an X indicates that the build has encountered an error.
When that finished with a green check mark, your versioned build release will be ready. On the top navigation bar, click on Code and your release should appear under the Releases panel in the right sidebar.
Mapeo is built with JavaScript programming language. To get started, you'll need to install Node.js development environment. If you already have Node.js installed you can skip this section.
You need to be at least on Node.js version 8 (or higher) for the mapeo-settings-builder to work properly. Head over to Node.js download page and select installer for your operating system.
Alternatively you can also use NVM (Node Version Manager) to install and manage multiple versions of Node.js on your computer.
Then close terminal and open again
https://docs.npmjs.com/cli/install
You'll see output on the terminal, but this is OK
If your computer is ready to create configurations, type
You should see output that looks something like
Now you're ready to move to build your configuration!
Type, 'cd`, then a space, then drag and drop the folder where the prepared assets are and press enter. It will look something like this
You will then be ready to run scripts directly in the folder.
This -s tells npm to be silent, so that you only see errors that are meaningful to you.
You will see something like the following output. Errors will be highlighted in RED with hopefully some helpful description so that you can remedy the issue.
You'll also see a .mapeosettings file inside of the build directory.
A .mapeosettings file is a tar file, similar to a zip file. You can see the contents of the file by changing the file extension to .tar and using any application that can extract tar files (such as 7zip, mentioned above).
Type the following into the terminal
You need to be at least on Node version 8 for the mapeo-settings-builder to work properly. If you need help, review the 'Preparing Computer' section and ensure you're on the latest version of mapeo-settings-builder.
You also may want to delete node_modules and install updated versions of the dependencies.
In Mac or Linux, in the terminal:
If you're having more issues, please open an issue on the GitHub repository or e-mail our support hotline.
It's important to increment the version when releasing new changes to your configuration. When you are ready to release a new version, you can use standard-version in the command line to automatically increment your config version and update the CHANGELOG.md file in your repository.
For more on versions with standard-version, see #use-conventional-commit-messages-to-increment-your-configuration-version
Compiling your configuration into a .mapeosettings file is the final step for testing and using your configuration in Mapeo Mobile and Desktop.
Building a configuration can be done in two ways:
Via the command line(with Node.js and mapeo-settings-builder)
