From c973e4d799284e9694142d2aa2bc9d4e98c58a33 Mon Sep 17 00:00:00 2001 From: Tiago Bento Date: Fri, 4 Oct 2024 21:44:28 -0400 Subject: [PATCH] Better READMEs --- _intellij-project/.idea/modules.xml | 1 + _intellij-project/README.md | 21 +- packages/maven-base/README.md | 8 + packages/root-env/README.md | 2 + repo/{docs/user_manual.md => MANUAL.md} | 276 +++++++++++++++++++++--- repo/README.md | 8 +- 6 files changed, 279 insertions(+), 37 deletions(-) rename repo/{docs/user_manual.md => MANUAL.md} (59%) diff --git a/_intellij-project/.idea/modules.xml b/_intellij-project/.idea/modules.xml index b9ae661573a..1ca7d1fed06 100644 --- a/_intellij-project/.idea/modules.xml +++ b/_intellij-project/.idea/modules.xml @@ -13,6 +13,7 @@ + diff --git a/_intellij-project/README.md b/_intellij-project/README.md index e90017885a9..4efcc9b030e 100644 --- a/_intellij-project/README.md +++ b/_intellij-project/README.md @@ -1,3 +1,20 @@ + + # KIE Tools @ IntelliJ IDEA To make it easier for developing Java-, Maven-based packages, this folder contains an IntelliJ IDEA project configured for select packages. It currently includes all Maven-based packages of KIE Tools. Two additional IntelliJ IDEA project modules are included too, given their "global" nature on the KIE Tools repository -- `scripts` and `root-env`. @@ -17,7 +34,9 @@ Once prompted by IntelliJ IDEA, select "Open" and choose this folder. You should now be able to develop all Java- and Maven-based projects normally. -For more information on Maven-based packages on KIE Tools, please refere to the [KIE Tools repo manual](../repo/docs/user_manual.md) +--- + +For more information on Maven-based packages on KIE Tools, please refere to the [KIE Tools :: Manual](../repo/docs/MANUAL.md). diff --git a/packages/maven-base/README.md b/packages/maven-base/README.md index 81d44a5ab28..1ab5a2ce9a0 100644 --- a/packages/maven-base/README.md +++ b/packages/maven-base/README.md @@ -17,6 +17,14 @@ ## @kie-tools/maven-base +Foundational files for Maven-based packages. + +- `pom.xml`: Centralized, common Maven configurations. Should be used as parent of Maven-based pacakges. +- `settings.xml`: Moslty repositories configuration. +- `index.js`: Essential scripts for configuring properties such as `-Drevision` and `-Dmaven.repo.local.tail`. + +For more information, refer to the [KIE Tools :: Manual](../../repo/docs/MANUAL.md#specifics--maven) + --- Apache KIE (incubating) is an effort undergoing incubation at The Apache Software diff --git a/packages/root-env/README.md b/packages/root-env/README.md index b1ef148b999..64841857f2d 100644 --- a/packages/root-env/README.md +++ b/packages/root-env/README.md @@ -17,6 +17,8 @@ ## @kie-tools/root-env +Foundational environment variables used by most packages of `kie-tools`. + --- Apache KIE (incubating) is an effort undergoing incubation at The Apache Software diff --git a/repo/docs/user_manual.md b/repo/MANUAL.md similarity index 59% rename from repo/docs/user_manual.md rename to repo/MANUAL.md index 4d3027e0894..3c2ce0e7f95 100644 --- a/repo/docs/user_manual.md +++ b/repo/MANUAL.md @@ -1,25 +1,46 @@ -# KIE Tools :: Repository Manual + + +# KIE Tools :: Manual This document contains all information related to the `kie-tools` as a Git repository. It describes its directory structure, concepts like "packages" and specifics on important tools like Maven, TypeScript, and Container images. +--- + ### Directory structure -| File | Description | | | | -| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | --- | --- | -| `packages/`
`examples/` | **Where the source code is**. There’s no distinction between these two dirs, except from the name and the convention as to where to put stuff. No dangling files are allowed inside these dirs, only other dirs containing packages. There is no package hierarchy. Both dirs have a flat structure. | | | | -| `repo/`
`scripts/` | Related to the monorepo itself. `repo` contains files describing the monorepo structure (I.e., packages DAG, for enabling partial clones with sparse checkout). `scripts` contains code to make the monorepo run smoothly. (E.g., `update-version-to` or `bootstrap`). | | | | -| `docs/`
`gifs/` | Files referenced externally in READMEs, for instance. Could be unified into a single directory only, probably with a better name. | | | | -| `package.json`
`pnpm-workspace.yaml` | Together they define the monorepo structure and make some commands available at the root dir. The root `package.json` acts like the glue holding everything together. It declares dependencies that are necessary for the monorepo to operate. Packages inside `scripts` are part of these dependencies. | | | | -| `.envrc`
`devbox.lock`
`devbox.json` | Direnv and Devbox configuration files. See these instructions to set it up. See [./../../NIX_DEV_ENV.md](./../../NIX_DEV_ENV.md) | | | | -| `.ci/` | Jeknins configuration for Apache release jobs | | | | -| `.github/` | GitHub configuration | | | | -| `.asf.yaml` | Apache Software Foundation (ASF) YAML for configuring GitHub features, as no one has access to the Settings tab of repos under the Apache organization. | | | | -| `.vscode/`
`_intellij-project/` | IDE configuration | | | | -| `.gitattributes`
`.gitignore`
`packages/*/.gitignore`
`examples/*/.gitignore` | Git stuff. `.gitignore` files must either by at the root of the repo, or at the root of a package. | | | | -| `.husky/`
`prettier.config.js`
`.prettierignore`
`packages/*/.prettierignore`
`examples/*/.prettierignore` | Code formatters configuration.
**Done**: Prettier defaults, package.json, XML
**To do**: Java, Go, Containerfiles, Python | | | | -| `.npmrc`
`.syncpackrc.json`
`patches/`
`pnpm-lock.yaml` | Related to NPM dependencies. .npmrc addresses https://github.com/pnpm/pnpm/issues/6300 and prevents 3rd party package binaries inside `node_modules` to access packages they don’t declare as dependencies via extend-note-path=false. Syncpack makes sure all `package.json` files declare the same version of dependencies. `patches` contains manual patches we do to NPM dependencies on `node_modules/.pnpm` `pnpm-lock.yaml` keeps NPM dependencies pinned to a specific version to make the monorepo future-proof. | | | | -| `.build-env-root` | Marker file used to not go looking for `build-env` configurations outside of the monorepo. More details about `build-env` below. | | | | +| File | Description | +| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `packages/`
`examples/` | **Where the source code is**. There’s no distinction between these two dirs, except from the name and the convention as to where to put stuff. No dangling files are allowed inside these dirs, only other dirs containing packages. There is no package hierarchy. Both dirs have a flat structure. | +| `repo/`
`scripts/` | Related to the monorepo itself. `repo` contains files describing the monorepo structure (I.e., packages DAG, for enabling partial clones with sparse checkout). `scripts` contains code to make the monorepo run smoothly. (E.g., `update-version-to` or `bootstrap`). | +| `docs/`
`gifs/` | Files referenced externally in READMEs, for instance. Could be unified into a single directory only, probably with a better name. | +| `package.json`
`pnpm-workspace.yaml` | Together they define the monorepo structure and make some commands available at the root dir. The root `package.json` acts like the glue holding everything together. It declares dependencies that are necessary for the monorepo to operate. Packages inside `scripts` are part of these dependencies. | +| `.envrc`
`devbox.lock`
`devbox.json` | Direnv and Devbox configuration files. See these instructions to set it up. See [NIX_DEV_ENV.md](./../../NIX_DEV_ENV.md) | +| `.ci/` | Jeknins configuration for Apache release jobs | +| `.github/` | GitHub configuration | +| `.asf.yaml` | Apache Software Foundation (ASF) YAML for configuring GitHub features, as no one has access to the Settings tab of repos under the Apache organization. | +| `.vscode/`
`_intellij-project/` | IDE configuration | +| `.gitattributes`
`.gitignore`
`packages/*/.gitignore`
`examples/*/.gitignore` | Git stuff. `.gitignore` files must either by at the root of the repo, or at the root of a package. | +| `.husky/`
`prettier.config.js`
`.prettierignore`
`packages/*/.prettierignore`
`examples/*/.prettierignore` | Code formatters configuration.
**Done**: Prettier defaults, package.json, XML
**To do**: Java, Go, Containerfiles, Python | +| `.npmrc`
`.syncpackrc.json`
`patches/`
`pnpm-lock.yaml` | Related to NPM dependencies. .npmrc addresses https://github.com/pnpm/pnpm/issues/6300 and prevents 3rd party package binaries inside `node_modules` to access packages they don’t declare as dependencies via extend-note-path=false. Syncpack makes sure all `package.json` files declare the same version of dependencies. `patches` contains manual patches we do to NPM dependencies on `node_modules/.pnpm` `pnpm-lock.yaml` keeps NPM dependencies pinned to a specific version to make the monorepo future-proof. | +| `.build-env-root` | Marker file used to not go looking for `build-env` configurations outside of the monorepo. More details about `build-env` below. | + +--- ### Concepts @@ -59,27 +80,28 @@ The monorepo is built on top of the `Package` abstraction, defined by `package.j - `dependencies` (optional) - Type: Map - Lists the RUNTIME dependencies of this package. - - Dependencies from inside the monorepo have version `”workspace:*”`. This is a `pnpm` feature. + - Dependencies from inside the monorepo have version `"workspace:*"`. This is a `pnpm` feature. - Dependencies from outside the monorepo have fixed versions. - Dependencies do come transitively when users do `npm install @my-scope/my-package`. - `devDependencies` (optional) - Type: Map - Lists the DEVELOPMENT / BUILD dependencies of this package. - - Dependencies from inside the monorepo have version `”workspace:*”`. This is a `pnpm` feature. + - Dependencies from inside the monorepo have version `"workspace:*"`. This is a `pnpm` feature. - Dependencies from outside the monorepo have fixed versions. - devDependencies don’t come transitively when users do `npm install @my-scope/my-package`. - Any other property accepted by NPM - Only relevant for NPM packages, of course. - See https://docs.npmjs.com/cli/v10/configuring-npm/package-json -- **`env/index.js`** +- `env/index.js` - Use if you need to configure `build:dev` and `build:prod` scripts. (E.g., skipping tests or changing the port of an app) - Mapping of environment variables to JSON - We never read the environment variables directly. Always through the JSON defined by `env/index.js` - Scoped per-package. Can’t access other packages by mistake. -- **`dist*` directories** +- `dist*` directories - Where build results usually end up. -- **…and whatever else the package needs!** - - Other than the `package.`json and the correct place to put test reports in JUnit XML format, packages are free to structure themselves in any way they need. +- …and whatever else the package needs + - Other than the `package.json` and the correct place to put test reports in JUnit XML format, packages are free to structure themselves in any way they need. + - Refer to [Conventions](#Conventions) to know more about how packages are structured. **Environment variables** @@ -92,11 +114,14 @@ The monorepo is built on top of the `Package` abstraction, defined by `package.j - Once it finds one, or the `.build-env-root` marker file, it stops. - There’s no automatic merging. Combining `env/index.js` files is done manually. Composition over inheritance! +--- + ### Conventions -1. **0.0.0 is the development version at `main`** +1. **`0.0.0` is the development version at `main`** - SemVer-compatible. - - Will absolutely never be resolved as “higher” than any published version. + - Will absolutely never be resolved as "higher" than any published version. + - Other branches will follow their stream name, with `999` replacing the variable part. E.g., `10.0.x` branch has version `10.0.999`. 1. **`package.json → version` is the source of truth for a package version** - It is always in SemVer format. - All language/tool-specific files must be derived from whatever version is defined on `package.json`. This ensures that the `update-version` script works as intended, as it simply updates the `package.json` version and runs a `bootstrap`. @@ -106,35 +131,37 @@ The monorepo is built on top of the `Package` abstraction, defined by `package.j 1. **`build:dev` and `build:prod` scripts must produce everything that dependent packages might need** - The difference between them is the amount of expensive checks/optimizations they do, but they must be able to produce a full version of the package equally. - An example is running linters or triggering compiler optimizations. In the very beginning, `build:dev` used to be called `build:fast`, so that kind of gives an idea of why there are two scripts. - - Build:prod should be understood as a “full build”, where everything you possibly want to do when building a package is done. + - Build:prod should be understood as a "full build", where everything you possibly want to do when building a package is done. - It’s not uncommon for build:dev and build:prod scripts to be identical. -1. **`build:dev` and `build:prod` must be “thread-safe”** +1. **`build:dev` and `build:prod` must be "thread-safe"** - Building packages in parallel is one of the things that makes the monorepo fast. Always assume other packages are building at the same time as your package. - If you follow the rules above, you’ll hardly hit a problem, unless you’re using a tool/command that can’t be run in parallel. In this case, finding an alternative way to achieve the results you want is going to be necessary, as we can’t assume a package will be built in isolation. - As of April 2024, the monorepo CI runs on the free tier of GitHub Actions, where machines have 2 available cores. Due to memory constraints, we run a sequential build. Locally, however, everyone has multiple cores available, and usually a lot of memory, so most people do `pnpm -r build:dev` locally after bootstrapping. -1. **Environment variables are exclusively read through `builld-env`, never directly.** +1. **Environment variables are exclusively read through `build-env`, never directly.** - This ensures encapsulation and good reports during `pnpm bootstrap`. 1. **There are no nested packages. Each package has one, and one only, `package.json` file.** - The package structure does not allow nested packages. - The monorepo has a flat structure architecture. 1. **Packages can’t reference other monorepo files outside of their directories using `..` on paths** -1. **Packages should only have knowledge about its own directory structure, never upwards.** + - Packages should only have knowledge about its own directory structure, never upwards. - Use `node_modules`, don’t ever do `../my-other-package/some/nested/dir`. Do `./node_modules/my-other-package/some/nested/dir`, or `./node_modules/@my-scope/my-package/some/nested/dir`. - This ensures packages only have access to what they declare as dependencies on their `package.json` files. 1. **Packages can’t mutate the monorepo’s file system outside of its directory structure** - The `node_modules` directory has a lot of symbolic links to directories that are shared between all packages. So changing it can potentially pollute the global scope and result in unpredictable behavior. - As a general rule, see the `node_modules` dir as read-only. 1. **Generated code is either ignored or versioned on Git.** - - If files are produced either during `bootstrap` or `build`, they must be either ignored by Git, or committed. Running `pnpm bootstrap` on a clean clone must never change any versioned file. + - If files are produced either during `bootstrap`, they must be either ignored by Git, or committed. Running `pnpm bootstrap` on a clean clone must never change any versioned file. If files are generated during `build`, they should not be versio in Git. 1. **Test results must be reported in JUnit XML format** - JUnit XMLs became the de-facto standard for test result reporting. - Having every test case reported using this format means we’ll always get good introspection and compatibility with test management tools, like Buildkite or TestRail. +--- + ### General good practices 1. Define the `package.json → kieTools → requiredPreinstalledCliCommands` property with what your package needs to be built. - This won’t fail any of the steps, but there’s a nice report on the `bootstrap` script that helps users understand their environment. -1. Don’t download stuff on scripts other than `install` +1. Prefer downloading stuff on scripts other than `install` - Ideally, any external resource you might need for the build should be fetched during the `bootstrap` script. Packages can hook into the root-level `bootstrap` script by defining an `install` script on their package.json file. - This allows the monorepo build to fail faster when there’s a problem fetching an external resource. 1. Make sure your package is buildable and testable on Windows, macOS, and Linux @@ -145,9 +172,9 @@ The monorepo is built on top of the `Package` abstraction, defined by `package.j 1. Use the same name for the package directory and `package.json → name` - In practice, the name of the directory doesn’t have meaning, but helps us navigate the repo. 1. Don’t use mutable versions anywhere - - “Latest”, or “dev”, or “SNAPSHOT” versions change with time, and can make the build break unexpectedly. - - More than that, when building an older tag or commit, pointing to “latest” will likely not work. - - Beware of unspecified versions too, as they often default to “latest”. + - `latest`, `dev`, or `-SNAPSHOT` versions change with time, and can make the build break unexpectedly. + - More than that, when building an older tag or commit, pointing to `latest` will likely not work. + - Beware of unspecified versions too, as they often default to `latest`. 1. Configure dependencies to have the same single version available to all packages - Pretty much like https://opensource.google/documentation/reference/thirdparty/oneversion - Try to keep the version string in a single place, or at least enforce it to be exactly the same as other declarations, like we do with Syncpack in the CI for NPM dependencies. @@ -157,6 +184,185 @@ The monorepo is built on top of the `Package` abstraction, defined by `package.j - Check if source maps are available. - Check if obfuscation is turned off. -asd +--- + +### Scripts + +A few scripts are available for general purpose usage on `kie-tools`. They're built prior to everything else and are available in the top-level `node_modules` dir, meaning any script can access them. They don't need to be declared as dependencies too since they're already a dependency of the root `package.json`. All of them can be invoked with `pnpm [script-name]`. + +- Used for everyday development + - [bootstrap](../../scripts/bootstrap/README.md): Runs when we execute `pnpm bootstrap`. + - [build-env](../../scripts/build-env/README.md): Environment variables management. + - [run-script-if](../../scripts/run-script-if/README.md): Shell-friendly conditional command execution +- Used when cloning `kie-tools` + - [sparse-checkout](../../scripts/sparse-checkout/README.md): Partially clone `kie-tools` and work on a subset of its packages. +- Mostly used by our automations + - [check-junit-report-results](../../scripts/check-junit-report-results/README.md): Checks JUnit XML files to see if tests failed. Used on our CI. + - [update-kogito-version](../../scripts/update-kogito-version/README.md): Updates the version of Kogito Maven dependencies. (E.g., `999-20240912-SNAPSHOT`, `999-SNAPSHOT` or `10.0.0`) + - [update-stream-name](../../scripts/update-stream-name/README.md): Updates this repo's stream name. (E.g., `main` or `10.0.x`) + - [update-version](../../scripts/update-version/README.md): Updates this repo's version (E.g., `0.0.0` or `10.0.999`) + +--- + +### Specifics # Maven + +To comply with the repository's conventions and concepts, like Packages, Maven usage has been mapped and documented here for reference. + +#### @kie-tools/maven-base + +Foundational package for other Maven-based packages to base themselves on. + +Used for writing `.mvn/maven.config` with `-Drevision`, `-Dmaven.repo.local.tail` and other necessary properties. +And for centralized `` and other necessary standard configurations + +All Maven-based packages should declare it as a `dependency` on their `package.json` files and its `pom.xml` as parent. + +```xml + + org.kie + kie-tools-maven-base + ${revision} + ./node_modules/@kie-tools/maven-base/pom.xml + +``` + +#### flatten-maven-plugin + +Due to CI friendly versions as well. Present on `maven-base` already, no need to configure it individually. +https://www.mojohaus.org/flatten-maven-plugin/ + +#### package.json → scripts → install: + +Has to be at least `node mvn.bootstrap.js` +The `mvn.bootstrap.js` script uses `@kie-tools/maven-base` to set up properties like `-Drevision`, `-Dmaven.repo.local.tail`. + +#### package.json → scripts → build:dev: + +Has to be at least `mvn clean install -DskipTests=$(build-env tests.run --not) -Dmaven.test.failure.ignore=$(build-env tests.ignoreFailures)` +Needs to install so that other Maven repos can reference it. + +#### package.json → scripts → build:prod: + +Has to be at least `mvn clean deploy -DdeployAtEnd -Dmaven.deploy.skip=$(build-env maven.deploy.skip) -DskipTests=$(build-env tests.run --not) -Dmaven.test.failure.ignore=$(build-env tests.ignoreFailures)` +This is important for the Release jobs to correctly deploy it. Of course, deploy is skipped by default, so it acts like `mvn clean install ...`. + +#### package.json → dependencies: + +If your Maven package depends on other Maven packages, you need to declare those in the `dependencies` section, not on `devDependencies`. +This ensures the release scripts know what other Maven packages need to be published alongside yours, and makes it easier to configure `-Dmaven.repo.local.tail` via `buildTailFromPackageJsonDependencies()` + +### Development + +This section contains relevant topics about developing packages hosted on KIE Tools. + +#### Setting up your environment + +- Nix.dev, Devbox, and `direnv` _**(recommended!)**_ + - See [NIX_DEV_ENV.md](./../../NIX_DEV_ENV.md) +- Traditional + - See [the top-level README.md](../../README.md#step-0-install-the-necessary-tools) + +#### Recommended IDEs + +- IntelliJ IDEA + - See [the top-level IntelliJ IDEA project](./../../_intellij-project/README.md) +- VS Code + - // TODO + +#### Running + +Usually, packages that can be developed individually (E.g., apps of any kind, or libraries with dedicated development apps) define a script called `start` on their `package.json`, for example, developing the DMN Editor can be done in these steps: + +1. `pnpm bootstrap -F dmn-editor...` +1. `pnpm -F dmn-editor^... build:dev` +1. `pnpm -F dmn-editor start` + +#### Changing libraries + +Packages that don’t contain an app (so-called libraries) can be developed in conjunction with apps that can be run. When developing libraries, they need to be rebuilt so that apps can be re-run with the changed version of the libraries you’re developing, and you can see the changes in effect. To do that, you can keep track of the libraries you’re building, and simply rebuild them with: + +`pnpm -F my-library build:dev` + +If you’re changing multiple libraries and don’t want to rebuild one by one, you can do: + +`pnpm -F my-app^... build:dev` + +This is much less error-prone, as you won’t forget to build one of the libraries that you might’ve changed. + +If your app doesn’t support live-reloading, you’ll need to re-run it too. If it does, rebuilding the libraries is enough. + +#### Multi-package live reloading + +Some webpack-based apps can be run with a special --env live parameter, so that rebuilding libraries is not necessary. This is great for developing the Boxed Expression Editor using the `dmn-editor` Storybook, + +`pnpm -F dmn-editor start --env live` + +#### (A) Adding a new package + +Simply add a directory with a `package.json` inside it, give it the properties you need and run `pnpm bootstrap` at the root dir. It is going to be part of the build now. + +#### (D) Removing a package + +If this package is public (I.e., doesn’t define "private": "true" on its `package.json`), it means it is published to the NPM registry, and there might be people depending on it. We should always publish a last version with an updated README telling people that the package was deleted, and what they should do about it. + +Ideally, we should deprecate packages before completely removing them. + +Private packages are never consumed directly, and can be removed without any additional process. The build will fail if there are references to the removed package that weren’t removed too. + +#### (M) Renaming a package + +Should be treated as removing and adding it. Don’t forget to rename the package directory AND `package.json → name`. + +If this package is public, consider leaving behind a package with the old name containing deprecation notices, and pointing to the new name. + +Adding a dependency to an existing package + +Change `package.json` manually and run `pnpm bootstrap` at the root directory. + +#### Formatting the code + +In practice, you don’t need to worry about this, as a pre-commit hook will format the changed files when you do `git commit`. + +The CI will also check if your code is properly formatted. + +#### Skipping tests + +- Conventionally, `build:dev` doesn’t run tests. +- If you really need to do `build:prod` locally, you can use the following environment variables to skip tests, as they usually take a while to run: + - `export KIE_TOOLS_BUILD__runTests=false` or + - `export KIE_TOOLS_BUILD__runEndToEndTests=false` + - Tests won’t run at all. + - `export KIE_TOOLS_BUILD__ignoreTestFailures=true` or + - `export KIE_TOOLS_BUILD__ignoreEndToEndTestFailures=true` + - Tests will run, but a failing test won’t fail the build. + +#### Understanding a package’s relationship with other packages + +- `pnpm list --depth Infinity --only-projects [pnpm filter?]` + - Will display the relationship the filtered packages have with other packages inside the repo. + - This is very similar to `mvn dependency:tree`. + +--- + +### Dependency management & security + +It’s really important to understand that the software toolchain has flaws, and we’re all exposed to downloading malicious code from time to time. + +There are, however, some things we can do to prevent ourselves from being in a dangerous situation. + +- Dependency management tools, like Maven, `pnpm`, or `pip`, have mechanisms to help us be safer. + - Lock files + - Commit SHA references + - Fixed versions + - Checksums +- When adding a dependency to the monorepo, be thoughtful about who’s behind that dependency and what methods you’re using to download it. +- Prefer projects that are very widely known, active and have a healthy community around it. +- Think about the scope of this dependency. + - Is this going to be used for development; or + - Will users need to install it to be able to run our packages? +- Licenses + - See https://www.apache.org/licenses/ + +--- -- +Feel free to proposed changes to this manual by sending a PR directly to this file. diff --git a/repo/README.md b/repo/README.md index 27195b6d740..01dbe86e23b 100644 --- a/repo/README.md +++ b/repo/README.md @@ -15,12 +15,18 @@ under the License. --> +This directory contains files related to the `kie-tools` monorepo itself. + +#### Manual + +The manual for the `kie-tools` repository. See [MANUAL.md](./MANUAL.md) + #### Repo dependencies version The related `build-dependencies-version.json` contains a centralized view of all required tools to correctly build the project. CI\CD tasks should rely on this file only, avoiding to hard-coding these version or store them in another place. Be aware that any key addition, change or removal can have an impact on CI\CD process -that rely on this file. Any tool version update must be update on this file as well, to guarantee the same +that rely on this file. Any tool version update must be updated on this file as well, to guarantee the same condition in all building processes. #### Packages dependency graph