Skip to content

Setup

Jump to bottom
Alex B edited this page Feb 13, 2023 · 29 revisions

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 points to the newly created empty GitHub repo (this might be helpful)
  4. The newly created GitHub repo should now contain the contents of this template, you can remove the temporary fodler now

Fill in the template

  • Replace vaadin-addon-template with the repository name
  • Replace the placeholder images
  • 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 XDEV Vaadin Addons-Team with role Maintain

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

  • Enable "Private vulnerability reporting"
  • Enable "Dependabot alerts"
  • Enable "Dependabot security updates"
  • Enable "Secret scanning"

Secrets and variables - Actions

Organization Secrets

These need to be added by an organization administrator

  • Required for releasing to Maven Central
    • MAVEN_CENTRAL_TOKEN
    • MAVEN_CENTRAL_USERNAME
    • MAVEN_GPG_PASSPHRASE
    • MAVEN_GPG_PRIVATE_KEY
  • Required for SonarCloud integration
  • Required for updates from the template

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

Add the Component on Vaadin Directory

  • Log into Vaadin Directory with our company account
  • Create a new Component (a initial release might be required so you get a zip that can be uploaded)

Component configuration

  • Description
    • Component Icon: Our company logo
    • Summary: Name of the component
    • Description: Description of the component - should look like this: 
      <Short component description in one sentence>

[More infos are available on GitHub](https://github.com/xdev-software/vaadin-chip-combobox)

⚠️ Currently no Maven downloads via Vaadin Directory are possible due to [#31](https://github.com/xdev-software/vaadin-chip-combobox/issues/31)<br>
Please use [Maven Central](https://mvnrepository.com/artifact/com.xdev-software/<TODO>) directly.

If you found a bug, want to suggest an improvement or have a question please open an issue at GitHub.
    • Add matching categories
  • Samples
    • Add some screenshots how the component looks like (you might reuse the images in assets)
  • Links
    • Add a link to the GitHub repo
    • Add a link to the GitHub issue tracker
    • Add a link to our company homepage
    • All other predefined links can be removed
  • Version (initial version)
    • Point the release notes to the GitHub Release, e.g. https://github.com/xdev-software/vaadin-chip-combobox/releases/tag/v3.0.1
    • Specify the supported framework, e.g. Upwards from Vaadin platform 23+
    • Maturity: Normally stable
    • Browser compatibility:
      • Normally all Chromium and Firefox browser platform independent desktop variants (should be tested before!)
        • Firefox
        • Opera (based Chromium)
        • Google Chrome
        • Microsoft Edge (based on Chromium)
      • Additional:
        • If you tested it for mobile platforms you can also check the right side (ignore Windows Phone it's no longer supported)
      • Internet Explorer is only available for Windows, no longer supported and can be ignored
      • Safari behaves like Internet Explorer for Apple devices and can also be ignored

Important: Do not forget to click onto "Save" (small green button on the top right)

Repository Details

Change the Repository Details/About

  • Add a description
  • Add a link (website) to the component on Vaadin Directory
  • Add some Topics/Labels, e.g. vaadin, vaadin-addon, ...
  • Disable Packages (since we deploy directly to Maven Central)

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.

Clone this wiki locally