inteligr8/maven-tiles
1
0
Fork 0
mirror of https://github.com/bmlong137/maven-tiles synced 2025-05-12 20:54:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

Initial Astro Starlight docs

Browse Source 
Change-Id: I6bf1cc851ade09f9791aedc162e39b29c966cdc0
This commit is contained in:
Mark Derricutt 2023-10-16 21:02:44 +13:00 committed by Mark Derricutt
parent ef05aa7efe
commit b1969808c7
No known key found for this signature in database
GPG Key ID: 0DFEAD8DBB8FAC31
16 changed files with 4699 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
.github/workflows/deploy.yml vendored Normal file
View File

@ -0,0 +1,40 @@
name: Deploy to GitHub Pages
on:
# Trigger the workflow every time you push to the `main` branch
# Using a different branch name? Replace `main` with your branch’s name
push:
branches:
- master
# Allows you to run this workflow manually from the Actions tab on GitHub.
workflow_dispatch:
# Allow this job to clone the repo and create a page deployment
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout your repository using git
uses: actions/checkout@v3
- name: Install, build, and upload your site
uses: withastro/action@v1
with:
path: docs # The root location of your Astro project inside the repository. (optional)
# node-version: 18 # The specific version of Node that should be used to build your site. Defaults to 18. (optional)
package-manager: pnpm@latest # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional)
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1

53
docs/README.md Normal file
View File

@ -0,0 +1,53 @@
# Starlight Starter Kit: Basics
[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
```
npm create astro@latest -- --template starlight
```
[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics)
[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/basics)
> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
## 🚀 Project Structure
Inside of your Astro + Starlight project, you'll see the following folders and files:
```
.
├── public/
├── src/
│ ├── assets/
│ ├── content/
│ │ ├── docs/
│ │ └── config.ts
│ └── env.d.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json
```
Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
Images can be added to `src/assets/` and embedded in Markdown with a relative link.
Static assets, like favicons, can be placed in the `public/` directory.
## 🧞 Commands
All commands are run from the root of the project, from a terminal:
| Command | Action |
| :------------------------ | :----------------------------------------------- |
| `npm install` | Installs dependencies |
| `npm run dev` | Starts local dev server at `localhost:4321` |
| `npm run build` | Build your production site to `./dist/` |
| `npm run preview` | Preview your build locally, before deploying |
| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` |
| `npm run astro -- --help` | Get help using the Astro CLI |
## 👀 Want to learn more?
Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).

40
docs/astro.config.mjs Normal file
View File

@ -0,0 +1,40 @@
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
// https://astro.build/config
export default defineConfig({
site: 'https://repaint-io.github.io',
base: '/maven-tiles',
integrations: [
starlight({
title: 'Tiles - Mixins For Apache Maven',
customCss: [
'./src/styles/custom.css',
],
social: {
github: 'https://github.com/repaint-io/maven-tiles',
},
sidebar: [
{
label: 'Maven Tiles',
items: [
{ label: "About", link: '/introduction/about/'},
{ label: "Using", link: '/introduction/using/'},
{ label: "Writing", link: '/introduction/writing/'}
]
},
// {
// label: 'Guides',
// items: [
// // Each item here is one entry in the navigation menu.
// { label: 'Example Guide', link: '/guides/example/' }
// ],
// }
// {
// label: 'Reference',
// autogenerate: { directory: 'reference' },
// },
],
}),
],
});

17
docs/package.json Normal file
View File

@ -0,0 +1,17 @@
{
"name": "maven-tiles",
"type": "module",
"version": "0.0.1",
"scripts": {
"dev": "astro dev",
"start": "astro dev",
"build": "astro build",
"preview": "astro preview",
"astro": "astro"
},
"dependencies": {
"@astrojs/starlight": "^0.11.1",
"astro": "^3.4.4",
"sharp": "^0.32.6"
}
}

4116
docs/pnpm-lock.yaml generated Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
docs/src/assets/houston.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 96 KiB

7
docs/src/content/config.ts Normal file
View File

@ -0,0 +1,7 @@
import { defineCollection } from 'astro:content';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
export const collections = {
docs: defineCollection({ schema: docsSchema() }),
i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
};

11
docs/src/content/docs/guides/example.md Normal file
View File

@ -0,0 +1,11 @@
---
title: Example Guide
description: A guide in my new Starlight docs site.
---
Guides lead a user through a specific task they want to accomplish, often with a sequence of steps.
Writing a good guide requires thinking about what your users are trying to do.
## Further reading
- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework

16
docs/src/content/docs/index.mdx Normal file
View File

@ -0,0 +1,16 @@
---
title: Tiles for Apache Maven
description: Modular Mixins for the Apache Maven build system
template: splash
hero:
tagline: Giving a fresh coat of paint to your Maven builds
image:
file: ../../assets/houston.webp
actions:
- text: Read the Tiles docs
link: /maven-tiles/introduction/about
icon: right-arrow
variant: primary
---
import { Card, CardGrid } from '@astrojs/starlight/components';

252
docs/src/content/docs/introduction/about.md Normal file
View File

@ -0,0 +1,252 @@
---
title: About
description: A Project Mixin Implementation for Apache Maven
---
The _tiles-maven-plugin_ is a Maven Plugin that brings a **modular**, **composition** based appraoch to Apache Maven builds.
## How do I make a Maven Tile?
Tiles are [plain Maven pom artifacts](https://github.com/maoo/maven-tiles-examples/tree/master/tiles) which contain parts of a Maven POM; every tile can contain
* build data, for example the license tags that a company wants to report on all their artifacts
* build aspects, for example the configurations of a plugin, such as Groovy, Java or Clojure.
* release aspects, for example the distribution management section
* references to other tiles
This could, for example, allow you to have build aspects consistent across your organization and open sourced, and the distribution of internal vs external artifacts kept in a single tile.
In the current single parent hierarchy, this is all duplicated.
## Where can't I use a Maven Tile?
The following are Repaint project definitions:
* **define: reactor build** - `pom.xml` that contains only modules, no plugins,
no dependencies, no dependency management, no plugin management. These are used as shortcuts to get your full project installed or tested.
* **define: multi-module build** - `pom.xml` that contains plugins and/or dependencies, dependency management, plugin management.
With those defined:
* You can use a tile in a reactor or multi-module build where the tile is a module and (a) only used in the other modules or (b) used in the parent with the inherits config turned off (so it is not inherited by the children). This is a side effect of how Maven works and we cannot work around it.
* We do not prioritize issues raised where you are using a multi-module build. These are the anti-thesis of Repaint.IO’s philosophy of composition over inheritance. If you raise the issue and it seems a reasonable use case we will look at it, but please be aware that it is unlikely to be looked at by us without an explicit reproducible test case.
## Execution Ids
Execution ids within tiles are prepended with the gav parameters of the tile that included the execution, for easier debugging/tracing.
If this is not desired, adding a configuration attribute `tiles-keep-id="true"` or entry
`<tiles-keep-id>true<tiles-keep-id>` will keep the original id. If you are using the _Kotlin Maven plugin_, you will need to use this or it will not work.
**tile.xml**
```xml
<?xml version="1.0" encoding="UTF-8"?>
<project>
<modelVersion>4.0.0</modelVersion>
<build>
<plugins>
<plugin>
<groupId>test</groupId>
<artifactId>test</artifactId>
<version>1.0</version>
<executions>
<execution>
<id>1</id>
</execution>
<execution>
<id>2</id>
<configuration tiles-keep-id="true" />
</execution>
<execution>
<id>3</id>
<configuration>
<tiles-keep-id>true</tiles-keep-id>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
<profiles>
<profile>
<id>test</id>
<build>
<plugins>
<plugin>
<groupId>test</groupId>
<artifactId>test</artifactId>
<version>1.0</version>
<executions>
<execution>
<id>4</id>
</execution>
<execution>
<id>5</id>
<configuration tiles-keep-id="true" />
</execution>
<execution>
<id>6</id>
<configuration>
<tiles-keep-id>true</tiles-keep-id>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>
```
In the above tile, executions with ids 1 and 4 will have their ids changed to
`io.repaint.tiles:execution-id-replacing-tile:1.1-SNAPSHOT::1` and
`io.repaint.tiles:execution-id-replacing-tile:1.1-SNAPSHOT::4` respectively, while executions with ids 2, 3, 5 and 6
will retain their original execution id.
## Build Smells
When migrating from a parent structure, it is worthwhile to take the opportunity to reduce your build smells.
You can do this gradually or in one go, depending on how your builds are done. By default, the plugin will strip all bad smells.
The following is an explanation of what is stripped and why those smells are bad. Richard and Mark will be putting together a short book with tutorials for a better approach to building using Maven, but this is the short explanation.
Note, these are only cleaned from the `tile.xml``, not from your `pom.xml``.
* **dependencymanagement** - this was always a poor substitute for composite poms. Composite poms - aka a pom only release
artifact that stores all related dependencies together. This allows your project to pull in only those dependencies
that it actually requires for release, and allow them to be directly overridden. Dependency management is only
for declaring the version of an artifact, and not that it is a dependency - it is better and more composable to
declare this specifically in a composite pom instead. Use version ranges so changes flow through.
* **pluginrepositories** and **repositories** - see [Repositories in POMs is a bad idea](http://blog.sonatype.com/2009/02/why-putting-repositories-in-your-poms-is-a-bad-idea/) - this has always
been a bad idea. Get rid of it as soon as possible.
* **dependencies** - putting them in a parent or tile prevents your user from exclusion, again composites are a much, much
better idea here. Just don’t use this section anywhere other than your actual artifact or composite poms.
Almost made a build smell:
- pluginmanagement - plugin management is used in parents to define all of the necessary options for a plugin but
not have that plugin actually run during the release of the parent artifact, and also give the child the option of
running it. The reason this is bad is that it is mostly not necessary. You should split your plugins up into tiles
so that they be pulled into a build as a standalone set of functionality that will always run and be properly configured.
Since they will reside in the tile.xml file, they will not be run when the tile is released. However, some plugins are
never run automatically - release and enforcer are two examples. These make sense to stay in pluginManagement.
If you need to use them, add them to your configuration section:
**pom.xml**
```xml
<build>
<modelVersion>4.0.0</modelVersion>
<plugins>
<plugin>
<groupId>io.repaint.maven</groupId>
<artifactId>tiles-maven-plugin</artifactId>
<version>2.15</version>
<configuration>
<buildSmells>dependencymanagement, dependencies, repositories, pluginrepositories</buildSmells>
<tiles>
<tile>groupid:antrun1-tile:1.1-SNAPSHOT</tile>
<tile>groupid:antrun2-tile:1.1-SNAPSHOT</tile>
</tiles>
</configuration>
</plugin>
</plugins>
</build>
```
## Parent structure
Tiles will always be applied as parents of the project that is built. Any orignal parent of that project will be added
as the parent of the last applied tile. So if you apply Tiles `T1` and `T2` to a project `X` with a parent `P`, the
resulting hierarchy will be `X` - `T1` - `T2` - `P`. Thus (see section _Additional Notes_), the definitions in the parent
can be overwritten by a tile, but not the other way around.
However, there are situations where you want to define your tiles in a parent, e.g. when you have a lot of artifacts
that are built in the same way. In this case you would want a structure like this: `X` - `P` - `T1` - `T2`. While you’d
maybe expect it to work this way if the tiles are included in `P`, due to the way Maven works there’s no way to know
where a configuration comes from. To still enable this use case you can manually choose a parent where the tiles will
be applied (in this case before `P`) resulting in the desired structure:
**pom.xml**
```xml
<parent>
<groupId>group</groupId>
<artifactId>P</artifactId>
<version>1.0.0</version>
</parent>
<artifactId>X</artifactId>
...
<build>
<plugins>
<plugin>
<groupId>io.repaint.maven</groupId>
<artifactId>tiles-maven-plugin</artifactId>
<version>2.37</version>
<configuration>
<applyBefore>group:P</applyBefore>
<tiles>
<tile>group:T1:1.0.0</tile>
<tile>group:T2:1.0.0</tile>
</tiles>
</configuration>
</plugin>
</plugins>
</build>
```
## Tile Ordering
In v2.19 and earlier, all tiles declared inside tiles are loaded after all tiles declared in the project. This meant
that all tiles declared inside tiles became ancestors to all tiles declared in the project.
In v2.20+, tile ordering has changed. All tiles are now loaded in order of when they are declared, recursively tracing
from tiles declared in a project down to the tiles declared within tiles.
Suppose your project declares tiles `T1` and `T2` and the `T1` tile declares tile `T3`. Earlier versions will load
these in the order `T1`, `T2`, and then `T3`. Using the notation used earlier on this page, this results in the Maven
project ancestry of `X` - `T3` - `T2` - `T1` - `P`. Later versions will load them in the order `T1`, `T3`, and then
`T2`. This results in the Maven project ancestry of `X` - `T2` - `T3` - `T1` - `P`.
In some cases, your project and tile hierarchy will include duplicate declaration of one tile. In these cases, the
tile is only included once. The latest declaration is used, resulting it showing up in the Maven project
ancestry as the one closest to the parent `P`. This guarantees it will be an ancestor to all tiles that included it.
## Mojos
There are two mojos in the plugin, attach-tile and validate. attach-tile is only used by the deploy/install
process and attaches the tile.xml. validate is for your use to ensure your tile is valid before releasing it - this
ensures it can be read and any errors or warnings about content will appear.
## Additional Notes
Some interesting notes:
* Tiles support version ranges, so use them. [1.1, 2) allows you to update and release new versions of tiles and have them
propagate out. Maven 3.2.2 allows this with the version ranges in parents, but it isn’t a good solution because of single
inheritance.
* You can include as many tiles as you like in a pom and tiles can refer to other tiles. The plugin will search through
the poms, telling you which ones it is picking up and then load their configurations in **reverse order**. This means the
poms _closer_ to your artifact get their definitions being the most important ones. If you have duplicate plugins, the one
closest to your pom wins.
* String interpolation for properties works. The plugin first walks the tree of tiles collecting all properties, merges them
together (closest wins), and then reloads the poms and interpolates them. This means all string replacement in plugins and
dependencies works as expected.
* Plugin execution is merged - if you have the same plugin in two different tiles define two different executions, they will
merge.
* The plugin works fine with alternative packaging. It has been tested with war, grails-plugin and grails-app.
## Final Notes
Tiles-Maven works best when **you** and **your team** own the tiles. I don’t recommend relying on open source tiles, always
create your own versions and always lock down versions of third party tiles, just like you would third party dependencies.
## Read More
* [The Original Tiles Maven plugin](https://github.com/maoo/maven-tiles) - although the essential start point is the same, the code is significantly different.
* [Mixin POM fragments](http://jira.codehaus.org/browse/MNG-5102)
* [Stack Overflow](http://stackoverflow.com/questions/11749375/import-maven-plugin-configuration-by-composition-rather-than-inheritance-can-it)
* [Maven Discussion](http://maven.40175.n5.nabble.com/Moving-forward-with-mixins-tc4421069.html)

25
docs/src/content/docs/introduction/using.md Normal file
View File

@ -0,0 +1,25 @@
---
title: Using Tiles
description: How to use Maven Tiles
---
...how do do use tiles...
## Composing Build functionality
As a use case, an example of how it will be used for my projects.
Richard will have:
* **java8-tile** - for those projects that are on Java 8
* **java11-tile** - for those projects that are on Java LTS (11)
* **groovy-tile** - which defines the build structure necessary to build a Groovy project, including GMavenPlus, GroovyDoc
and Source plugins
* **java-tile** - for Java only projects which include all the Javadoc and Source plugins
* **s3-tile** - for our Servlet3 modules, which includes Sass, JSP compilation and Karma plugins and depends on the groovy-tile
* **github-release-tile** - for artifacts that release to Github (open source)
* **nexus-release-tile** - for artifacts that release to our local Nexus (not open source)
This allows me to open source all my tiles except for the nexus tile, and then decide in the final artifact where I will
release it.

101
docs/src/content/docs/introduction/writing.md Normal file
View File

@ -0,0 +1,101 @@
---
title: Writing a Maven Tile
description: How to write a Maven Tile
---
A Maven Tile is made up of a `pom.xml` and a `tile.xml`.
The `pom.xml` is a basic Maven project using the packaging type of `tile`, and the inclusion of the `tiles-maven-plugin`, along with release plugin configuration (often coming itself from a tile).
The POM would be minimal, only declaring the `name`, `groupId`, `artifactId`, `version`, `description`, and `packaging` (tile) attributes and generally only a declaration of the Maven Tiles plugin.
The tiles plugin will only have a `configuration` element defined when using other tiles (generally, you use at least one - a release tile).
**pom.xml**
```xml
<project>
<groupId>io.repaint.maven</groupId>
<artifactId>license-tile</artifactId>
<version>1.1-SNAPSHOT</version>
<packaging>tile</packaging>
<description>Contains consistent license information.</description>
<modelVersion>4.0.0</modelVersion>
<build>
<plugins>
<plugin>
<groupId>io.repaint.maven</groupId>
<artifactId>tiles-maven-plugin</artifactId>
<version>2.37</version>
<extensions>true</extensions>
<configuration>
<filtering>false</filtering>
<tiles>
<tile>io.repaint.tiles:github-release-tile:[1.1, 2)</tile>
</tiles>
</configuration>
</plugin>
</plugins>
</build>
</project>
```
With the packaging `tile`, the plugin will look for the attached `tile.xml``, do some basic validation on it and attach it as an artifact.
When the `<filtering>` configuration item is specified as `true` - then standard Maven resource filtering for `@project.version@` style references is applied to the `tile.xml` file prior to install/deploy.
**tile.xml**
```xml
<?xml version="1.0" encoding="UTF-8"?>
<project>
<modelVersion>4.0.0</modelVersion>
<licenses>
<license>
<name>The Apache Software License, Version 2.0</name>
<url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
<distribution>repo</distribution>
</license>
</licenses>
</project>
```
## Using Snapshots of Tiles
`-SNAPSHOT` versions of tiles work when installed into your local `~/.m2/repository`, however - if you wish to use a _published_ SNAPSHOT - you will need to declare a `<repository>` in your `pom.xml` that support SNAPSHOTs.
Review the [introduction to repositories](https://maven.apache.org/guides/introduction/introduction-to-repositories.html) section on the Apache Maven website.
If you don’t wish to include `<repository>` definitions in your project source, declaring them in an activated `<profile>` in your `~/.m2/settings.xml` file is a viable alternative.
**📌 NOTE**\
This introduces an element of inconsistentcy/non-reproducability to your build and should be done with care.
## Transcluding Tiles
A tile can define the tiles plugin if it wishes to cascade tile inclusion, or it can use the extended `tile.xml` syntax:
**tile.xml**
```xml
<?xml version="1.0" encoding="UTF-8"?>
<project>
<modelVersion>4.0.0</modelVersion>
<licenses>
<license>
<name>The Apache Software License, Version 2.0</name>
<url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
<distribution>repo</distribution>
</license>
</licenses>
<tiles>
<tile>io.repaint.tiles:ratpack-tile:[1,2)</tile>
</tiles>
</project>
```
Although this will appear to not validate when editing in an IDE, the tile plugin will strip off the `tiles` section when processing and use it directly.

11
docs/src/content/docs/reference/example.md Normal file
View File

@ -0,0 +1,11 @@
---
title: Example Reference
description: A reference page in my new Starlight docs site.
---
Reference pages are ideal for outlining how things work in terse and clear terms.
Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what your documenting.
## Further reading
- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework

2
docs/src/env.d.ts vendored Normal file
View File

@ -0,0 +1,2 @@
/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />

5
docs/src/styles/custom.css Normal file
View File

@ -0,0 +1,5 @@
:root {
--sl-content-width: 60rem;
--sl-line-height: 1.3rem;
--sl-text-sm: 10pt;
}

3
docs/tsconfig.json Normal file
View File

@ -0,0 +1,3 @@
{
"extends": "astro/tsconfigs/strict"
}