Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/ACCESS_TOKENS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ we know when they expire and if someone leaves the CoMPAS Organization which one

## Overview Access Tokens

Below tokens are al registered under the CoMPAS Organisation as Action Secret.
Below tokens are all registered under the CoMPAS Organisation as Action Secret.

| Token Name | Owner | Expire Date |
|--------------------------|-----------------|-------------|
Expand All @@ -16,7 +16,7 @@ Below tokens are al registered under the CoMPAS Organisation as Action Secret.
| ORG_GITHUB_ACTION_SECRET | Pascal Wilbrink | 30/06/2023 |
| SONAR_TOKEN | Pascal Wilbrink | - |

Below tokens are al registered under the CoMPAS Organisation as Dependabot Secret.
Below tokens are all registered under the CoMPAS Organisation as Dependabot Secret.

| Token Name | Owner | Expire Date |
|--------------------------|-----------------|-------------|
Expand Down
4 changes: 2 additions & 2 deletions docs/DEPENDABOT.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ updates:
```

- (1): This configures the GitHub Maven Repository that Dependabot can use to search for new versions of CoMPAS Dependencies.
- (2): This will check if the newest versions of GitHub Actions are used. Default it will scan the directory ".githuib/workflows"
- (2): This will check if the newest versions of GitHub Actions are used. Default it will scan the directory ".github/workflows"
under the directory defined here (in this case "/").
- (3): This will scan the Maven Plugins and Dependencies defined in the pom.xml files. The GitHub Maven Repository is also
defined here.
Expand Down Expand Up @@ -76,7 +76,7 @@ pull request to merge it into the default branch.

## Adding Dependabot Secret DB_GITHUB_PACKAGES

Tot access GitHub Packages a secret DB_GITHUB_PACKAGES needs to be created.
To access GitHub Packages a secret DB_GITHUB_PACKAGES needs to be created.
- First create a new personal access token from https://github.com/settings/tokens. Tokens can only be created as personal tokens.
The token also must have the right "read:packages".
- Next create a new organisation secret from https://github.com/organizations/com-pas/settings/secrets/dependabot with the value of
Expand Down
2 changes: 1 addition & 1 deletion docs/DEPLOYMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
We deploy the (native) Docker image of all CoMPAS services to Docker Hub. This way, it can be pulled and deployed into environments of your choice (OpenShift for example).

## Quick Deployment instructions (under construction)
The following instructions are terminal instructions for publishing a Quarkus docker image to Docker Hub. This should be done by a Github Action in the future.
The following instructions are terminal instructions for publishing a Quarkus docker image to Docker Hub. This should be done by a GitHub Action in the future.

```
docker login # Creating a Docker session
Expand Down
2 changes: 1 addition & 1 deletion docs/DEVELOPING.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ Username should be your GitHub username, password can both be your own [encrypte
or a [Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token).

## IDEs
If your IDE is supported by sonarlint (both IntelliJ IDEA and the Eclipse IDE are supported), it is recommended to install it.
If your IDE is supported by SonarLint (both IntelliJ IDEA and the Eclipse IDE are supported), it is recommended to install it.
It provides immediate feedback on most sonar issues. Running tests individually is often possible in IDEs without invoking maven.
Please consult the documentation of your IDE for setting up the project through maven integration.

Expand Down
24 changes: 12 additions & 12 deletions docs/GITHUB_ACTIONS.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
# Github Actions
Every repository within the CoMPAS Github organization need a default set of Github Actions.
[Github Actions](https://github.com/features/actions) are CI/CD steps within a Github Repository that you can configure. This way, you can ensure that certain steps (like building) are always triggered on for example a commit push.
# GitHub Actions
Every repository within the CoMPAS GitHub organization need a default set of GitHub Actions.
[GitHub Actions](https://github.com/features/actions) are CI/CD steps within a GitHub Repository that you can configure. This way, you can ensure that certain steps (like building) are always triggered on for example a commit push.

Within CoMPAS, we define the following 'must have' Github Actions:
Within CoMPAS, we define the following 'must have' GitHub Actions:
- [Building](#building)
- [REUSE check](#reuse-check)
- [SonarCloud](#sonarcloud)
- [Docker Hub Deployment](#docker-hub-deployment)

More to follow.

Github Actions are configured using YAML files. These files are stored in the `.github/workflows` directory of a specific repository.
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
Expand Down Expand Up @@ -65,7 +65,7 @@ jobs:

A few points to remember:
- (1): By default, all actions are triggered on a push action.
- (2): This step creates a custom settings.xml for authenticating for Github Packages. For more information,
- (2): This step creates a custom settings.xml for authenticating for GitHub Packages. For more information,
check the [Contributing file](https://github.com/com-pas/contributing/blob/master/CONTRIBUTING.md).
- (3): This is a default for building a Maven project. It may differ in some cases, please feel free to adjust it.

Expand All @@ -92,7 +92,7 @@ A few points to remember:
This is the only thing that has to be done. After this, it will be checked on every push.

### REUSE badge
For transparancy, CoMPAS repositories also include a REUSE badge in their README for fast checking the REUSE compliance.
For transparency, CoMPAS repositories also include a REUSE badge in their README for fast checking the REUSE compliance.

Two steps are needed to get a REUSE badge to work:

Expand All @@ -110,11 +110,11 @@ After doing all these steps, everything is set up for the REUSE check.
## SonarCloud
For static code analysis, CoMPAS is using [SonarCloud](https://sonarcloud.io/). To configure this, there are several steps that needs to be done.

1. Go to the [CoMPAS Github organization settings](https://github.com/organizations/com-pas/settings/profile), and click on "Installed Github Apps". SonarCloud is listed here already (because we are already using it). Click on the 'configure' button next to it.
1. Go to the [CoMPAS GitHub organization settings](https://github.com/organizations/com-pas/settings/profile), and click on "Installed GitHub Apps". SonarCloud is listed here already (because we are already using it). Click on the 'configure' button next to it.
2. In the "Repository access" section, select the repository you want to add. By default, not every repository is added as an extra check.
3. Create a new project in [SonarCloud](https://sonarcloud.io/projects/create).
4. Select the repository to be analyzed, click Set Up.
5. Choose the Analysis Method "With Github Actions".
5. Choose the Analysis Method "With GitHub Actions".
6. It first tells you to create a SONAR_TOKEN secret in your repo. Go to your repository -> Settings - Secrets -> New repository secret -> Name: SONAR_TOKEN. Value: Copy the value from the SonarCloud website into here. Then save the secret
7. Select Maven as the option that best describes our build and **remember the projectKey**. and create a `sonarcloud_analysis.yml` file in the `.github/workflows` directory containing the following source code running.

Expand Down Expand Up @@ -168,7 +168,7 @@ jobs:

A few points to remember:
- (1): By default, all actions are triggered on a push action.
- (2): Creates a custom `settings.xml` having the credentials for the Github Packages.
- (2): Creates a custom `settings.xml` having the credentials for the GitHub Packages.
For more information, check our [Contributing](https://github.com/com-pas/contributing/blob/master/CONTRIBUTING.md).
- (3): Replace the `<insert project key>` with the project key you copied.

Expand Down Expand Up @@ -219,10 +219,10 @@ jobs:
```

A few points to remember:
- (1): By default, the docker image is only deployed on release. This way we have a strict deployment flow, and versions always have the same content. For more information about types of releases, check the [Github Actions documentation](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#release).
- (1): By default, the docker image is only deployed on release. This way we have a strict deployment flow, and versions always have the same content. For more information about types of releases, check the [GitHub Actions documentation](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#release).
- (2): Before deploying to Docker Hub, we need to login first. This can be done by executing a GitHub Action. In this example, `DOCKER_HUB_USERNAME` and `DOCKER_HUB_PASSWORD` are used, which are secrets stored at [CoMPAS organization](https://github.com/organizations/com-pas/settings/secrets/actions). For more information about the username and password, ask in the the [Slack channel](https://app.slack.com/client/TLU68MTML).
- (3): Extract the tag name from Git and use that as version to be set with Maven (${{ steps.extract_tagname.outputs.tagname }}).
- (4): Creates a custom `settings.xml` having the credentials for the Github Packages.
- (4): Creates a custom `settings.xml` having the credentials for the GitHub Packages.
For more information, check our [Contributing](https://github.com/com-pas/contributing/blob/master/CONTRIBUTING.md).
- (5): Building and publishing the docker image is build tool / framework specific. By default, CoMPAS services are using Quarkus and Maven. Deploying to Docker Hub is quite easy using Quarkus and maven, it's just a matter of building in combination with setting some properties. In this example, we use the `quarkus-profile` parameter instead of including all the parameters. This way, we can define profile specific properties in our `application.properties` file (For more information about this, check our [Docker Hub Deployment page](./DEPLOYMENT.md)):

Expand Down
38 changes: 19 additions & 19 deletions docs/HOME.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,9 @@ Use your best judgment, and feel free to propose changes to this document in a p
* [Copyright Guidelines](#definition-of-done)
* [How-to begin](#how-to-begin)
* [Copyright and Licensing](#copyright-and-licensing)
* [Github Project Boards](#github-project-boards)
* [GitHub Project Boards](#github-project-boards)

[Github Pages](#github-pages)
[GitHub Pages](#github-pages)


## Code of Conduct
Expand All @@ -36,7 +36,7 @@ Technical Steering Committee [CoMPAS-tsc@lists.lfenergy.org](mailto:CoMPAS-tsc@l
By contributing to the CoMPAS project, you accept and agree to the following terms and conditions for your present and future contributions submitted to CoMPAS.

All contributions to this project are licensed under the license stipulated at the corresponding sub-repository.
Except where otherwise explicitely indicated, CoMPAS is an open source project licensed under the [Apache License, version 2.0](http://www.apache.org/licenses/LICENSE-2.0/).
Except where otherwise explicitly indicated, CoMPAS is an open source project licensed under the [Apache License, version 2.0](http://www.apache.org/licenses/LICENSE-2.0/).

The project requires the use of the [Developer Certificate of Origin (DCO)](https://developercertificate.org/).
The DCO is a legally binding statement asserting that you are you have the right to submit your contribution and to license it under the project's applicable license.
Expand All @@ -61,15 +61,15 @@ Note that checks will be performed during the integration in order to require th

## Community refinements

Every monday there is a CoMPAS Community Refinement at 10AM CET. The event is available at the CoMPAS mailing list [calendar](https://lists.lfenergy.org/g/CoMPAS/calendar) and can be subscribed to.
Every Monday there is a CoMPAS Community Refinement at 10AM CET. The event is available at the CoMPAS mailing list [calendar](https://lists.lfenergy.org/g/CoMPAS/calendar) and can be subscribed to.

### Prepared topics

Every friday before the refinement meeting on Monday, all topics are published on the #compas channel on our [LFEnergy Slack](https://lfenergy.slack.com/).
Every Friday before the refinement meeting on Monday, all topics are published on the #compas channel on our [LFEnergy Slack](https://lfenergy.slack.com/).

### Add your own topics

Everybody can suggest topics for the refinement. To do this, join the [LFEnergy Slack](https://lfenergy.slack.com/) if not already, and put your topics in the #compas channel. You can just do this by writing a message like "I want to add something to the refinement this monday, namely..." or add a comment to the already prepared topics if available (see [Prepared topics](#prepared-topics)).
Everybody can suggest topics for the refinement. To do this, join the [LFEnergy Slack](https://lfenergy.slack.com/) if not already, and put your topics in the #compas channel. You can just do this by writing a message like "I want to add something to the refinement this Monday, namely..." or add a comment to the already prepared topics if available (see [Prepared topics](#prepared-topics)).

### Reporting Bugs and Suggesting Enhancements

Expand Down Expand Up @@ -116,7 +116,7 @@ Continuous integration is set up to run on all branches automatically and will o

Continuous integration is setup automatically on all contributions. However, it's faster to iterate locally to fix problems than waiting for the status checks to finish.
There are many tools that can be used to do the verifications that are enforced by all status checks. The most simple and universal tool is maven, but IDE integrations
can be used to get more immediate feedback. Most of the team uses IntelliJ IDEA, but others IDEs can be used, for exemple the Eclipse IDE.
can be used to get more immediate feedback. Most of the team uses IntelliJ IDEA, but others IDEs can be used, for example the Eclipse IDE.

### Definition of Done

Expand Down Expand Up @@ -144,7 +144,7 @@ On the [developing](DEVELOPING.md) page information about tooling can be found.

#### Open Community Calls

It's good to know that every other monday, we are having a so called Open Community Call. Everyone participating in the CoMPAS project can join
It's good to know that every other Monday, we are having a so called Open Community Call. Everyone participating in the CoMPAS project can join
and talk about and ask question about the CoMPAS project.

When the Open Community Calls are taking place, can be found at the [General CoMPAS mailing list calendar](https://lists.lfenergy.org/g/CoMPAS/calendar).
Expand All @@ -157,7 +157,7 @@ If you have something to add, please add it to the agenda and notify everyone on

One of the first important things, is to meet the community. Feel free to introduce yourself by joining the channel 'compas' on [LF Energy Slack](https://slack.lfenergy.org/)!

The Slack channel is the first communication platform within the CoMPAS project (besides email and the Github platform), so if you need help for example you can use Slack!
The Slack channel is the first communication platform within the CoMPAS project (besides email and the GitHub platform), so if you need help for example you can use Slack!

#### Documenting
A good (open source) project requires documentation. We have two places for our documentation
Expand All @@ -170,33 +170,33 @@ about CoMPAS in general (like roadmap and the community call agendas).
#### Architecture and technologies

For all architecture and technology choices (for example frameworks, build tools, database choices, etcetera),
please check the source code (duh!) and our [CoMPAS Architecture Github Pages](https://com-pas.github.io/compas-architecture/).
please check the source code (duh!) and our [CoMPAS Architecture GitHub Pages](https://com-pas.github.io/compas-architecture/).

### Copyright and Licensing

Copyright and license information is done on per-file basis. We use the specification of [REUSE](https://reuse.software/spec/)
to ensure that copyright information of the project is clear and can be analuzed in an automated fashion.
to ensure that copyright information of the project is clear and can be analyzed in an automated fashion.

Every source code repository within CoMPAS has a Github Action for checking against the REUSE specification.
Every source code repository within CoMPAS has a GitHub Action for checking against the REUSE specification.

For more information, check the [Copyright Guidelines](STYLEGUIDE.md#copyright-guidelines) section.

### Github Project Boards
### GitHub Project Boards

For managing the CoMPAS issues created in all the separate repositories, we use the [Projects Board](https://github.com/orgs/com-pas/projects) of Github.
CoMPAS uses 2 different Project Boards: One for [Pull Requests](https://github.com/orgs/com-pas/projects/2) and one for the [Issues](https://github.com/orgs/com-pas/projects/1).

When creating Pull Requests or Issues, it will automatically create issues or Pull Requests on the Project Boards.
This is done by the Automate Projects Github Action (take a look at the [action from the Data Service](https://github.com/com-pas/compas-core/blob/master/.github/workflows/automate-projects.yml) for example).
Changing the status of Issues / Pull Requests is also handled automatically by the Github Action.
This is done by the Automate Projects GitHub Action (take a look at the [action from the Data Service](https://github.com/com-pas/compas-core/blob/master/.github/workflows/automate-projects.yml) for example).
Changing the status of Issues / Pull Requests is also handled automatically by the GitHub Action.

Issues and Pull Requests can be moved on both the Project Boards and on the boards of the specific repository itself. It synchronizes automatically.

## Github Pages
## GitHub Pages

This site is provided as a [github pages site](https://com-pas.github.io/contributing/).
The content is maintained and edited on [Github](https://github.com/com-pas/contributing) in the directory "docs".
Contributors are only allowed to contribute by editing the content on Github and must do so by presenting their modifications as *pull-request* to the community.
This site is provided as a [GitHub pages site](https://com-pas.github.io/contributing/).
The content is maintained and edited on [GitHub](https://github.com/com-pas/contributing) in the directory "docs".
Contributors are only allowed to contribute by editing the content on GitHub and must do so by presenting their modifications as *pull-request* to the community.
The diagrams on this page are created using [DrawIO](https://github.com/jgraph/drawio-desktop/releases)
and follow [Unified Modeling Language (UML)](https://www.omg.org/spec/UML/).
The drawIO design file is available on this site: [/blob-files/CoMPAS.drawio](blob-files/CoMPAS.drawio).
Expand Down
Loading