These are notes to assist developers with creating a new FOLIO module as a repository, preparing initial setup files, and configuration.
Choose module name
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-2892. Specify “Development Team: FOLIO DevOps” (our team will prioritize and schedule).
Configuration at GitHub
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 “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.)
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.
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 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.
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).
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: 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 for master branch has not yet run.
For front-end modules: package.json, .eslintrc, Jenkinsfile, etc.
Get the initial basic source files and other configuration files added first.
Also add the Jenkinsfile to initiate the CI processing.
Do this early so that CI can assist.
The Jenkinsfile setting “
runSonarqube = true” 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.
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.
Configuration of the new repository can only be done by people with appropriate access. See the folio-infrastructure lokalise-push procedure.
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.