diff --git a/docs/ACCESS_TOKENS.md b/docs/ACCESS_TOKENS.md index 773d79a..6bad41f 100644 --- a/docs/ACCESS_TOKENS.md +++ b/docs/ACCESS_TOKENS.md @@ -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 | |--------------------------|-----------------|-------------| @@ -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 | |--------------------------|-----------------|-------------| diff --git a/docs/DEPENDABOT.md b/docs/DEPENDABOT.md index a67586c..d52a6a2 100644 --- a/docs/DEPENDABOT.md +++ b/docs/DEPENDABOT.md @@ -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. @@ -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 diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 7ec82e2..01ce752 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -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 diff --git a/docs/DEVELOPING.md b/docs/DEVELOPING.md index 3cbb844..b6cb586 100644 --- a/docs/DEVELOPING.md +++ b/docs/DEVELOPING.md @@ -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. diff --git a/docs/GITHUB_ACTIONS.md b/docs/GITHUB_ACTIONS.md index eaaf640..fb4018a 100644 --- a/docs/GITHUB_ACTIONS.md +++ b/docs/GITHUB_ACTIONS.md @@ -1,8 +1,8 @@ -# 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) @@ -10,7 +10,7 @@ Within CoMPAS, we define the following 'must have' Github Actions: 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 @@ -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. @@ -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: @@ -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. @@ -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 `` with the project key you copied. @@ -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)): diff --git a/docs/HOME.md b/docs/HOME.md index 5148c7c..5178c7e 100644 --- a/docs/HOME.md +++ b/docs/HOME.md @@ -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 @@ -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. @@ -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 @@ -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 @@ -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). @@ -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 @@ -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). diff --git a/docs/STYLEGUIDE.md b/docs/STYLEGUIDE.md index d964b4f..93f2d16 100644 --- a/docs/STYLEGUIDE.md +++ b/docs/STYLEGUIDE.md @@ -36,9 +36,9 @@ For more tips on using REUSE (for example with a small command line tool), check ## Java StyleGuide - The project uses modern java, feel free to use any new APIs provided by the current java version (currently java 11). -- New API classes and methods should be documented with javadoc. Write higher level documentation for classes and lower level documentation for methods. For example, ... +- New API classes and methods should be documented with Javadoc. Write higher level documentation for classes and lower level documentation for methods. For example, ... - User-facing configuration options and general design decisions should be documented (where?) -- We use standard configurations of well known tools like checkstyle and sonarqube to enforce a coherent coding style, please consult those tools for justifications on these rules. +- We use standard configurations of well known tools like checkstyle and SonarQube to enforce a coherent coding style, please consult those tools for justifications on these rules. As a simple yet instructive example, consider ... ```java @@ -50,4 +50,4 @@ As a simple yet instructive example, consider ... ## Git Commit Messages As usual, please start the commit message with a short line describing the commit, then leave a blank line, then give more context and explanations. -You can use GitHub's integrations, for exemple to link to existing issues. In general, pull requests with more than one commits will be squashed when merged in master. +You can use GitHub's integrations, for example to link to existing issues. In general, pull requests with more than one commits will be squashed when merged in master.