diff --git a/docs/DEVELOPING.md b/docs/DEVELOPING.md index 43445a2..8afdd65 100644 --- a/docs/DEVELOPING.md +++ b/docs/DEVELOPING.md @@ -13,7 +13,7 @@ What's GitHub? It's where you're looking right now! (Joking!). We are using GitHub for hosting our Git repositories. GitHub is being used for creating issues and creating Pull -Requests to review / merge each others code. +Requests to review / merge each other's code. ### LFX Security Tool For checking potential security issues, we use the [LFX Security Tool](https://security.lfx.linuxfoundation.org/#/e8b6fdf9-2686-44c5-bbaa-6965d04ad3e1/licenses). @@ -33,7 +33,7 @@ Every GIT repository can build its artifacts and publish these to GitHub Package Other GIT repositories can then add GitHub Packages as Maven repository to their build tool. See below how to do both action for the specific tools. -To use GitHub Packages a username and token is needed. The username is your GitHub username. The token can be generate +To use GitHub Packages a username and token is needed. The username is your GitHub username. The token can be generated in GitHub by going to your settings, Developer settings, Personal access tokens. Generate a new token here and make sure that the scope "read:packages" is enabled. Use this token below to configure the build tools. @@ -105,70 +105,6 @@ $ mvn package eclipse:eclipse After importing the projects with either method, install SonarLint for quicker feedback on potential sonar issues. -## GitHub Actions - -### Settings.xml during GitHub Action for GitHub Packages -During multiple GitHub Actions (like building and SonarCloud analysis), the custom `settings.xml` file is needed because it needs access to the GitHub Packages -to download certain artifacts. We can do this by adding the following step **before** the GitHub Packages repository is needed. - -```yaml -- name: Create custom Maven Settings.xml - uses: whelk-io/maven-settings-xml-action@v18 - with: - output_file: custom_maven_settings.xml - servers: '[{ "id": "github-packages-compas", "username": "OWNER", "password": "${{ secrets.GITHUB_TOKEN }}" }]' -``` - -This basically creates a custom `settings.xml` at location `custom_maven_settings.xml`. This file can be passed to maven in the next step -by using `mvn -s custom_maven_settings.xml` and perhaps some extra parameters you wish for. - -For the `servers` part, we again have the `github-packages-compas` ID that needs to be the same. We have an `OWNER` username (this is the default, because -it needs to have a username) and a password which is the GITHUB_TOKEN that's always available. - -## Releasing software - -### Create a release - -To create a release of the software we are using the release functionality of GitHub. Under the tab 'code' there is a section -'Releases'. When selected all current releases will be displayed, and a new release can be created (draft release). -The standard branch to create a release from should be the "main" branch, so the code changes have been reviewed. - -For every repository that creates a software product (artifacts or docker images) a GitHub Action ('release-project.yml') -is defined. This action runs when a release is created. -```yaml -on: - release: - types: [released] -``` - -Depending on the type of project different steps will be executed. -Common steps are: -- Checking out the source code, -- Extracting the entered version from the Git Tag. -- Set version using Maven -- Setup Maven settings.xml file - -Depending on the type of project other steps will be executed. Some examples are: -- Build and publish the software to GitHub Packages using Maven -- Build and publish the docker image to DockerHub using Maven -- Build and publish the docker image to DockerHub using NPM and Docker - -### Publish artifacts using Maven - -To publish artifacts to GiHub Packages a distribution section needs to be added to pom.xml of the root. -```xml - - - github-packages-compas - GitHub Packages - https://maven.pkg.github.com/com-pas/[repo-name] - - -``` -The ID is the same as the ID used for the repository section [above](#github-packages-in-maven). -This way the same credentials will be used to connect to GitHub Packages as described [above](#maven-local-settingsxml-for-github-packages). -Replace "[repo-name]" with the name of the repository from CoMPAS. - ## Others ### Adding custom badges to your README @@ -183,4 +119,4 @@ In case of the LFX Security Tool, we used the following: - Insert 'LFX Security Tool' as the label. - Insert the API to use, in case of our LFX Security tool projects we use [this API](https://api.security.lfx.linuxfoundation.org/v1/project/e8b6fdf9-2686-44c5-bbaa-6965d04ad3e1/issues). - Now you can query using JsonPath. To get all open high issues from the 'CoMPAS Core' project, use `issues[?(@['repository-name'] == 'compas-core')]['high-open-issues']`. -- Choose a color and a pre- or surfix text. +- Choose a color and a pre- or suffix text. diff --git a/docs/GITHUB_ACTIONS.md b/docs/GITHUB_ACTIONS.md index d0fd14d..eaaf640 100644 --- a/docs/GITHUB_ACTIONS.md +++ b/docs/GITHUB_ACTIONS.md @@ -12,6 +12,24 @@ More to follow. Github Actions are configured using YAML files. These files are stored in the `.github/workflows` directory of a specific repository. +## Maven settings.xml during GitHub Action for GitHub Packages +During multiple GitHub Actions (like building and SonarCloud analysis), the custom `settings.xml` file is needed because it needs access to the GitHub Packages +to download certain artifacts. We can do this by adding the following step **before** the GitHub Packages repository is needed. + +```yaml +- name: Create custom Maven Settings.xml + uses: whelk-io/maven-settings-xml-action@v18 + with: + output_file: custom_maven_settings.xml + servers: '[{ "id": "github-packages-compas", "username": "OWNER", "password": "${{ secrets.GITHUB_TOKEN }}" }]' +``` + +This basically creates a custom `settings.xml` at location `custom_maven_settings.xml`. This file can be passed to maven in the next step +by using `mvn -s custom_maven_settings.xml` and perhaps some extra parameters you wish for. + +For the `servers` part, we again have the `github-packages-compas` ID that needs to be the same. We have an `OWNER` username (this is the default, because +it needs to have a username) and a password which is the GITHUB_TOKEN that's always available. + ## Building All source code repositories need some kind of building step. By default, all source code repositories use Maven as the build tool. diff --git a/docs/PULL_REQUESTS.md b/docs/PULL_REQUESTS.md new file mode 100644 index 0000000..d0774b2 --- /dev/null +++ b/docs/PULL_REQUESTS.md @@ -0,0 +1,29 @@ +# Pull requests + +To add code to the different repositories the code is build in a feature branch and merged back to the branch ``develop`` +using a pull request. No direct committing is allowed to the branches ``develop`` and ``main``. +When a release is created the branch ``develop`` is merged to the branch ``main`` using a pull request. +In some repositories the branch ``develop`` is skipped and not there. Feature branches are merged directly to the branch +``develop`` + +## Creating a pull request + +When creating a pull request to merge a feature branch back we need to be aware that some information about the pull +request is used to generate the release notes. + +- **Title**: The title is added to the release notes, so give it a nice descriptive one. +- **Labels**: Use a label to add the pull request to correct section in the release notes. + - ``enhancement``: The pull request adds as a new feature. + - ``bug``: The pull request solves a bugfix. + - ``tooling``: Change or update to tooling used to build project. + +There is a special label ``dependencies`` used by dependabot for updating dependencies. +These are grouped together in a separate section. +If no label is added the pull request will be added to the section ``Other Changes`` at the bottom of the release notes. + +The following labels cause the pull request to be ignored in the release notes: +- ``wontfix`` +- ``duplicate`` +- ``invalid`` + +**Remark**: The label ``tooling`` is not a standard label, so that may need to be created by the first developer using it. \ No newline at end of file diff --git a/docs/RELEASES.md b/docs/RELEASES.md new file mode 100644 index 0000000..2e4ed0a --- /dev/null +++ b/docs/RELEASES.md @@ -0,0 +1,85 @@ +# Releasing software + +## Create a release + +To create a release of the software we are using the release functionality of GitHub. Under the tab ``code`` there is a section +``Releases`` (Right side). When selected all current releases will be displayed, and a new release can be created (draft release). +The standard branch to create a release from should be the ``main`` branch. + +Enter the following values when creating a new release: +- **Choose a tag**: Enter a new version using semantic versioning, for example ``0.1.4``. + Also press ``Create new tag`` to create the new label. +- **Target**: This should normally be ``main``. +- **Release title**: Name of the release, use the following template ``Release of ``, for instance + ``Release 0.1.4 of SCL Auto Alignment Service`` +- **Describe the release**: These are the release notes, press the button ``Auto-generate release notes`` to generate these. + Check [Configure release notes generation](#configure-release-notes-generation) to configure how these are generated. + +Now press ``Publish release`` to create the release. For every repository that creates a software product (artifacts or docker images) +a GitHub Action (``release-project.yml``) is defined. This action runs when a release is created. +```yaml +on: + release: + types: [released] +``` + +Depending on the type of project different steps will be executed. +Common steps are: +- Checking out the source code, +- Extracting the entered version from the Git Tag. +- Set version using Maven +- Setup Maven settings.xml file + +Depending on the type of project other steps will be executed. Some examples are: +- Build and publish the software to GitHub Packages using Maven +- Build and publish the docker image to DockerHub using Maven +- Build and publish the docker image to DockerHub using NPM and Docker + +## Publish artifacts using Maven + +To publish artifacts to GiHub Packages a distribution section needs to be added to pom.xml of the root. +```xml + + + github-packages-compas + GitHub Packages + https://maven.pkg.github.com/com-pas/[repo-name] + + +``` +The ID is the same as the ID used for the repository section in [Maven Build](DEVELOPING.md#github-packages-in-maven). +This way the same credentials will be used to connect to GitHub Packages as described [Maven Build](DEVELOPING.md#maven-local-settingsxml-for-github-packages). +Replace ``[repo-name]`` with the name of the repository from CoMPAS. + +## Configure release notes generation + +During creating of a release we will use the GitHub feature to automatically generate the release notes using the pull requests. +The way these release notes are created can be configured by adding/updating the file ``release.yml`` to the directory ``.github``. + +The content of the file ``release.yml`` is currently: +```yaml +changelog: + exclude: + labels: + - wontfix + - duplicate + - invalid + categories: + - title: New Features + labels: + - enhancement + - title: Bugfixes + labels: + - bug + - title: Tooling changes + labels: + - tooling + - title: Dependency updates + labels: + - dependencies + - title: Other Changes + labels: + - "*" +``` + +This will group different pull request using the different labels. diff --git a/docs/_includes/sidebar.html b/docs/_includes/sidebar.html index 96c99fd..be6aa6d 100644 --- a/docs/_includes/sidebar.html +++ b/docs/_includes/sidebar.html @@ -27,6 +27,12 @@

  • Github Actions
    • +
  • + Pull requests +
    • +
  • + Releasing software +
  • Dependabot