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
Most setup can be done by your development team, following this document.
If assistance is needed then raise a FOLIO DevOps Jira ticket so that the correct permissions are set on the repo, and an appropriate Jira project can be created (if applicable).
Configuration at GitHub
If the “New” button is not available to you at github.com/folio-org then seek FOLIO DevOps assistance.
The repository must be “public” and not the default “private”.
Otherwise follow the GitHub prompts to create a new repository, and if needed to then import an existing code base.
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 relevant project’s FOLIO issue tracker.
Ensure that access is configured for the relevant FOLIO GitHub Teams. Note that front-end module repositories also need the “bots” Team (with Write access) to enable the “translations” facility.
Add a concise “About” description to the GitHub repository. Consider that this will also be utilised elsewhere. This description is near the top-right of your GitHub front page. (If the “Edit” button is not available to you, then see the “support” advice above.)
Note: The configuration of “branch protection” and its “required checks” can only be done after there has been an initial pull-request (and must be done within one week of its opening). Also, for front-end repositories, the GitHub Actions Workflows need to be operational.
Add initial files
There are various module development bases and facilities to assist with starting a new module. Also follow the structure of a relevant well-configured 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 the required PERSONAL_DATA_DISCLOSURE.md form.
Add the required LICENSE and CONTRIBUTING.md and README.md files.
Ensure that the required copyright and license statement is near the top of the README. Use the initial year of creation for the date. (In subsequent years it will become a date range.)
Ensure that any package.json and pom.xml etc. type of configuration file has the appropriate required “licence” elements.
In the bottom “Further information” section of the README, add a link to your project issue tracker.
Refer to the Wiki FOLIO Code of Conduct.
Add .editorconfig configuration 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, POM, Jenkinsfile, etc.
Get the initial basic source files and other configuration files added first.
Then add the Jenkinsfile to initiate the CI processing. Do this early so that CI can assist. Note: The 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 for master branch has not yet run.
Note: The api-lint and api-schema-lint and api-doc are now done via GitHub Workflows, not via Jenkinsfile.
Frontend specific
For front-end modules: package.json, .eslintrc, GitHub Workflows, etc.
Get the initial basic source files and other configuration files added first.
New front-end repositories will use GitHub Actions Workflows (see our document or follow an existing similar repository).
When the code and configuration is in place, then this new repository needs to be manually added to Sonarcloud. Seek FOLIO DevOps assistance.
Module documentation
As explained in the FAQ Where is developer documentation located, one of the principles of FOLIO module development is that module documentation is managed along with its source code.
Consider the guide to increase visibility of module documentation which provides some tips for module developers to improve the discoverability and usability of their module documentation.
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 builds.