Skip to content

aem-design/aemdesign-archetype

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Archetype Project

build_status Quality Gate Status Maven Central github license github issues github last commit github repo size github repo size github release Visit AEM.Design Gitter

This project is used to create a new aem-design project base

This base can be updated by generating an archetype from existing project and copying relevant parts to this project.

To use

To create a new project base framework from scratch follow these steps:

  • Install the archetype to your local .m2 repo. Ensure you are in this aemdesign-archetype directory.
cd aemdesign-archetype
mvn install
  • Use this archetype to generate a new project framework. Ensure you are in this aemdesign-archetype directory. Edit groupId, package and artifactId to be specific to your project.
mkdir test-structure
cd test-structure
mvn archetype:generate \
  -DarchetypeGroupId=aemdesign \
  -DarchetypeArtifactId=aemdesign-archetype \
  -DarchetypeVersion=0 \
  -DgroupId=design.aem \
  -Dpackage=aemdesign-aem \
  -DartifactId=aemdesign-parent

You should now have a base maven project within test-structure that can be used as a starting point for your new aemdesign project.

cd aemdesign-parent
chmod +x deploy-local

Below deploy-local command builds and deploys, created aemdesign-parent project to local AEM author instance. Make sure you have local AEM Instance upon running.

./deploy-local

This should build and deploy, your project successfully to local AEM Instance.

NOTE: We need Yarn to be installed for compose submodule build. Check if Yarn v1.7.0 is installed

yarn -version

If yarn is not installed, run the below command.

brew install yarn

Full Process

Following is the process of how to use this archetype to create a new project and run post creation tasks.

This process will create a new base project for you, rename it to parent convention, init git and update all scripts to be executable.

  1. Create base project
mvn archetype:generate \
    -DarchetypeGroupId=design.aem \
    -DarchetypeArtifactId=aemdesign-archetype \
    -DarchetypeVersion=1.0.22 \
    -DgroupId=au.com.projectx.aem \
    -DgroupTitle="ProjectX AEM" \
    -DartifactId=projectx \
    -DartifactTitle="ProjectX AEM" \
    -DparentArtifactId=projectx-parent \
    -DparentArtifactName="ProjectX :: AEM :: parent" \
    -Dpackage=projectx \
    -DpackageGroup=projectx \
    -Dversion=0.1 \
    -DcomponentGroupTitle=ProjectX \
    -DappsFolderName=projectx \
    -DcontentFolderName=projectx \
    -DconfFolderName=projectx \
    -DclientLibsFolderName=projectx \
    -DclassNamespace=au.com.projectx.aem \
    -DappsParent=aemdesign
  1. Rename generated project folder to parent
mv projectx projectx-parent
cd projectx-parent
  1. Init git with initial content and create first Tag to allow automated project versioning to work.
git init
git add .
git commit -m init
git tag -a 0.1 -m init
  1. Update script permissions
find . -type f  -name "deploy" -exec chmod +x {} \;
find . -type f  -name "deploy-*" -exec chmod +x {} \;
find . -type f  -name "test-spec*" -exec chmod +x {} \;
find . -type f  -name "install" -exec chmod +x {} \;
find . -type f  -name "package" -exec chmod +x {} \;
find . -type f  -name "pull" -exec chmod +x {} \;
find . -type f  -name "stats" -exec chmod +x {} \;
find . -type f  -name "seleniumhub-*" -exec chmod +x {} \;
  1. Package project to test everything
./package

Generate Archetype from existing project

To generate an updated archetype based on existing maven project run the following command from the parent repo

mvn archetype:create-from-project

This will generate new archetype content in target directory. This process can be done ongoing or at the end of the project copying across relevant and optimal things that are good as a starting point for a project.

Available properties

groupId Maven GroupId Type Example Default
groupId Base Maven groupId namespace au.com.aemdesign design.aem
groupTitle group title AEM.Design
artifactId ArtifactId prefix simple name aemdesign aemdesign
artifactTitle artifact title title ${artifactId}
parentArtifactId parent artifact id simple name aemdesign ${artifactId}-parent
parentArtifactName parent artifact name simple name aemdesign ${groupId} :: ${artifactId} :: parent
package Java Source Package simple name aemdesign ${artifactId}
packageGroup Content Package Group name simple name ${groupTitle}
version Version version 0.1-SNAPSHOT 0.1-SNAPSHOT
componentGroupTitle componentGroup for component title AEM Design ${groupTitle}
appsParent /apps folder for inherited components simple name aemdesign aemdesign
appsFolderName /apps folder name simple name aemdesign ${artifactId}
contentFolderName /content folder name simple name aemdesign ${artifactId}
confFolderName /conf folder name simple name ${artifactId}
clientLibsFolderName /etc/clientlibs folder name simple name ${artifactId}
classNamespace namespace for classes namespace ${artifactId}

Post Generate Task

After you have generated your new project run the following command to set execute permissions for scripts

find . -maxdepth 2 -type f  -name deploy -o -name deploy-* -o -name install -o -name build -o -name package -o -name serve -o -name pull -o -name stats -o -name watch | xargs -I{} chmod +x {}

Versioning

Git Describe

To test git versioning run

git describe

this will show you generated version message with latest tag and how many commits since tag.

If you get an error:

fatal: No annotated tags can describe

create or overwrite an existing tag with a message:

git tag 1.0 1.0^{} -f -m "initial tag"

Version Convention

Version numbers should follow semver format:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality in a backwards-compatible manner, and
  • PATCH version when you make backwards-compatible bug fixes.

Please use MAJOR and MINOR version in Tags, PATCH version will be automatically added as a commit count since the last tag using the git describe.

Version Meaning

Version 1.0.3-SNAPSHOT means that current checkout has uncommitted changes Version 1.0.3 means that current checkout does not have uncommitted changes and is 3 commits ahead of the tag 1.0

Version Number Commits

You do not need to commit POM files with venison numbers as they will be generated.

Minimal core artifacts required for providing overridable AEM components.

Supporting content for AEMDesign development and maintenance.

To build

To ensure the project builds correctly locally run:

mvn -Dvault.useProxy=false -DskipTests -e -U clean package

To deploy

To build and deploy the project to your local aem instance (default localhost:4502), in the project root run:

./deploy-local

To create a release

Releases are managed via the maven plugins versions-maven-plugin and maven-scm-plugin

Version numbers should follow the SemVer convention.

The release process

Prepare release branch

In preparation for a release, create a new git release branch from the current master snapshot branch:

  1. Create a new release branch.
    • mvn scm:branch -Dbranch=release/<version> -Dmessage="creating release branch <version>"
  2. Ensure you are on the new release branch.
    • git checkout release/<version>
  3. Update the maven version parameter.
    • mvn versions:set -DnewVersion=<version>
  4. Check the version number was correctly applied and confirm.
    • mvn versions:commit -Pdeploymentpackage
  5. Commit the updated version numbers to the release branch.
    • mvn scm:checkin -Dmessage="updating version numbers"

Release new version

Once the testing cycle has been completed and all code fixes have been applied to the remote release branch, we create a git tag of our version and deploy the maven aemdesign-aem-core artifact to the remote maven repository and merge our release to master branch.

  1. Ensure we are on the release branch for aemdesign-aem-core.
  2. Raise a Gitlab Merge Request from the relase branch to master branch, adding the necessary reviewers.
  3. Create the git tag.
    • mvn scm:tag -Dtag="<version>"
  4. Deploy the maven release artifacts to the remote maven repository
    • <ToDo>
  5. Accept the aemdesign-aem-core Merge Request and delete the release branch.
  6. Update the Release history section in this readme with details of the new release.

Release history

| Version | Release Date | Features | |: ---------|:-------------:| :----------------------------:| | 1.0 | 12/09/2018 | Initial release after refactor| | | | | | | | | | | | |