Skip FOLIO Project Navigation

GitHub and Twitter:

Introduction

These are notes to assist developers with creating a new FOLIO module as a repository, preparing initial setup files, and configuration.

Choose module name

Take care to choose wisely for the module name. It will be disruptive to change that.

Devops assistance

Open Jira tickets, so that the project is integrated into Jenkins, the correct permissions are set on the repo, and an appropriate Jira project can be created (if applicable). There is one example at FOLIO-2113. Specify “Development Team: Core: Platform” and “Labels: platform-backlog devops” to be prioritized and scheduled.

Configuration at GitHub

If the “New” button is not available to you at github.com/folio-org then contact FOLIO infrastructure (e.g. via the issue tracker or the #support channel).

Otherwise follow the GitHub prompts to create a new repository, and if needed to then import an existing repository.

The following first few items can only be done by the initial creator of the repository or its owners, and should happen early. Use its “Settings” area. (If the “Settings” tab is not available to you, then see the “support” advice above.)

Disable the Issues and Wiki via Settings. We use the FOLIO resources instead. Do this as soon as possible, so that issues are created in the FOLIO issue tracker.

Ensure that access is configured for the relevant FOLIO GitHub Teams.

Add a concise Description to the GitHub repository. Consider that this will also be used elsewhere. This Description is near the top of your GitHub front page. (If the “Edit” button is not available to you, then see the “support” advice above.)

Add initial files

There are facilities to assist with starting a new module. For front-end modules see stripes-cli. For back-end RMB-based modules see mod-rmb-template. Otherwise follow the structure of a relevant existing module.

Follow the Naming conventions guidelines.

The Commence a module - structure and configuration guide explains a consistent layout.

Compare initial files with an existing FOLIO module repository (e.g. mod-notes, ui-users). The Stripes/UI/backend modules might be slightly different (e.g. CHANGELOG.md = NEWS.md).

Add LICENSE and CONTRIBUTING.md and README.md files.

Ensure that the copyright and license statement is near the top of the README. Use the initial year of creation for the date.

Ensure that any package.json and pom.xml etc. type of configuration file has the appropriate “licence” elements.

In the bottom “Further information” section of the README, add a link to your project issue tracker.

Add .editorconfig file.

Add initial NEWS.md or CHANGELOG.md file.

If necessary, add a basic .gitignore file. Developers will have their own ~/.gitignore_global to handle most.

Add specific configuration files

Follow similar existing repositories.

The Commence a module - structure and configuration guide explains a consistent layout and explains each type of file (so not repeated here).

Backend specific

For back-end modules: descriptors/ModuleDescriptor-template.json, Dockerfile, Jenkinsfile, etc.

Get all of the source files and other configuration files established first. Then add the Jenkinsfile to initiate the CI processing. Note: Its Jenkinsfile needs to be committed directly to master branch. If it is done via a pull-request then that will fail, as the initial base Sonar scan has not yet run.

Frontend specific

For front-end modules: package.json, .eslintrc, Jenkinsfile, etc.

Configure Lokalise

For UI modules, when the new repository is ready, and its translations directory is configured as explained, then add the new module to Lokalise to enable the translators to operate.

Configuration of the new repository can only be done by people with appropriate access. See the folio-infrastructure lokalise-push procedure.

Next steps

When a new module has been fully established and its artifacts are being deployed, follow the guides to install it to platform and reference environments for snapshot and testing builds.