Setup

Important

For company internal projects

If you are planning to create something that you want to release publicly:
🛑 STOP - Talk to the corresponding people (e.g. AB-xdev) BEFORE you start coding a single line!
Publicly available components need to full-fill some important criteria, e.g. modularity, extensability, code style, maintenance planning, etc.

If you want to use this template do the following:

Initialize Git

⚠️ Do not use the "Create a new repository"-Button of the GitHub UI. It will create a new repo with a unrelated history which will cause merge problems when syncing/updating with upstream.

1. Clone the addon-template repository locally into a new (temporary) folder
2. Create a new (empty - with no content) GitHub repository
3. Change the origin of the cloned repo so that it points to the newly created empty GitHub repo (this might be helpful) and push it
4. The newly created GitHub repo should now contain the contents of this template, you can remove the temporary folder now

Fill in the template

• Replace template-placeholder with the repository name
  • Exception: Do not replace it inside update-from-template.yml!
• Check the Readme

Repository Settings

Some settings may require a public repository

General

• Disable wikis (they are not used by us because the lack versioning and accessibility)
• Disable discussions (issues are sufficient)
• Disable projects (we have a "super"-project that already takes care of that - we don't need a separate project per repo)
• Enable "Automatically delete head branches" (so that there are no "dead"-PR branches)
• Enable "Limit how many branches and tags can be updated in a single push" (Up to 5)

Collaborators and teams

• Add the corresponding Team with role Admin
• Add the Dependency Updates-Team with role Write (if you want dependency updates, which is highly recommended)

Branches

• Default branch: develop
• Create and enable branch protection for
  • develop (Development-Branch)
  • master ("Current Release"-Branch)

Actions - General

• Workflow permissions: "Read repository contents permission"
• Enable "Allow GitHub Actions to create and approve pull requests"

Pages

• Source: Deploy from a branch
• Branch: gh-pages Folder: / (root)

Code security and analysis

This is now managed organization wide and no longer has to be configured manually

Secrets and variables - Actions

Organization Secrets

These need to be added by an organization administrator

• Required for releasing to Maven Central
  • SONATYPE_MAVEN_CENTRAL_PORTAL_USERNAME
  • SONATYPE_MAVEN_CENTRAL_PORTAL_TOKEN
  • MAVEN_GPG_PASSPHRASE
  • MAVEN_GPG_PRIVATE_KEY
• Required for SonarCloud integration
  • SONAR_TOKEN - The token belongs to https://github.com/xdev-gh-bot
• Required for updates from the template
  • UPDATE_FROM_TEMPLATE_PAT - The PAT belongs to https://github.com/xdev-gh-bot

GitHub apps

• Install SonarCloud (required for SonarCloud integration)

Integrate SonarCloud

• Create a new project in our SonarCloud organisation and name it exactly like the created repo name
  • Setup "New code" by using "Number of days"=30
• Disable "Automatic Analysis" in "Administration/Analysis method"
• To check if SonarCloud is working go to the GitHub actions Tab and execute the Sonar workflow manually
• Check the results and possibly fix them

Repository Details

Change the Repository Details/About

• Add a description
• Add some Topics/Labels, e.g. api-client, <Productname>-client, ...

Keeping up to date with the template

Once in a week a GitHub action is executed that tries to sync the changes from the template.

If changes are found a PR is created.

Check the PR changes from time to time and merge them into the develop.