Child pages
  • Using Git with Sling
Skip to end of metadata
Go to start of metadata

This page documents decisions we made while finding out how to best work with Git as well and various quality-of-life tips related to Git.

Cloning the Sling git repositories

This is documented in the Sling Aggregator Github module.


Force pushing to the master branch, or to other branches that are shared with others, is discouraged. It makes collaboration harder and potentially impacts other tools as well - Jenkins, SonarCloud, etc. If you need time experimenting and fiddling with history, it's better to start working with an individual repository and then bring it to Sling, once it's stable.

Merging pull requests from contributors

Maintaining a linear history in git is preferred, especially for small contributions. To that end, we should always rebase + merge commits on GitHub instead of merging them ( which creates a merge commit ).

Each commit should be buildable and correct by itself, as much as possible. Therefore, when asking contributors for revisions to small contributions (1 commit)  we should ask them to amend the  and force-push the commit so that they do not create multiple artificial commits. This is beneficial when reviewing history for changes and also when running git bisect .  Unfortunately it is not possible to rebase + squash + merge using the GitHub UI, so we need to either ask the contributors to amend + force-push, or to perform these operations locally.

It is also important to maintain the original author of the pull request, giving them credit for their contribution. This is also useful when compiling various contribution metrics, e.g. in Kibble.

Accepting new significant contributions

When accepting an external contribution we will import it into the sling-whiteboard repository. Before making a new release, we will move it to its own repository with the release manager also proposing a proper artifact id and therefore repository name.

It is recommended to provide ownership information when accepting new contributions by maintaining the original Author git header.

See also dev@sling - Where do we put new git modules?

Code donations

In case of code developed externally and not initially intended to be hosted at the ASF IP clearance is required. The general rules are outlined at . For a hands-on example, the Sling Journal-based Content Distribution is a good example:

Creating new repositories

Git repository creation

Repository creation is open only to PMC members. If you are not part of the PMC please ask on and someone will do this for you.

When creating new repositories we follow the convention of deriving the repository name from the Maven artifactId. The full logic can be found in the script, but the gist is:

  1. Append sling- to the artifact id if not there ( required by ASF infra conventions )
  2. Replace all dots with dashes ( ASF infra does not allow dots in repository names )

It is recommended to announce the intention on the mailing list, without calling a formal vote, since renaming repositories requires ASF infra manual intervention.

Creating a new repository is done using the web UI at . Please fill in the fields in the following manner:

  • Name: artifact Id , dots replaced with slashes. Should not contain the sling-  prefix as the form will auto-insert it in the 'Generated Name' field
  • Repository Description: name  from the pom.xml, otherwise short summary of the form Apache Sling Foo
  • Commit Notification List:
  • GitHub Notification List:

See a recent example below

Permission propagation

The scripts will be created in gitbox and github at the same time, but permissions will be granted to the GitHub repository sometime later, due to the way ASF infra tooling works. If permissions don't appear in two hours, raise an INFRA ticket. In the meantime you can use the gitbox backend to push your changes.

Importing existing code from the whiteboard

If you have code that exists in the whiteboard and you want to move it to a separate repository it is recommended to keep the history. The steps to achieve that are below, given that ${FOLDER} is the folder from the Sling Whiteboard that you want to move to a new repository, and that ${NEW_REPO}  is the name of the new repository. The new repository should already be created.

1. Clone the whiteboard repository

$ git clone
$ cd sling-whiteboard

2. Reduce the repository to only the subfolder you're interested in

$ git filter-branch --prune-empty --subdirectory-filter ${FOLDER}

3. Change the origin remote URL to the desired one

$ git remote set-url origin${NEW_REPO}.git

4. Review your changes and push them

$ ls -1
$ git log
$ git push -u origin master


Update the repo manifest

Regenerate the default.xml manifest form the sling-aggregator repo using  groovy collect-sling-repos.groovy > default.xml .

Boilerplate files

Ensure that at a minimum the repository contains the following files:

  • - brief description of the module
  • LICENSE - the standard Apache-2.0 license file (available in the sling-aggregator repo)
  • - reference to the Apache Software Foundation code of conduct (available in the sling-aggregator repo)
  • - reference to the Apache Sling contribution guidelines (available in the sling-aggregator repo)
  • Jenkinsfile - delegates to the Apache Sling Pipeline library ( example available in all repos, for instance see the Jenkinsfile for the sling-org-apache-sling-api repository )
  • .gitignore
  • .asf.yaml for Github metadata, see git - .asf.yaml features
    • tags: include initially sling  and java  (or other programming language, as applicable )
    • homepage: module documentation on Sling website, or the Sling homepage if none exists
    • description: the name from the pom.xml 


The sling-aggregator/ script automates the creation of badges for the README. You will need a valid GitHub token for it. To add the badges for just a single repository, run.

$ ./ ../ ${NEW_REPO}

Enroll in Kibble

The repository should be added as a source in the Apache Kibble dev instance to make sure development statistics are collected from it. The Kibble dev instance repository list should be refreshed periodically, but if you don't see the data in a week or so ask on about it.

Onboard to SonarCloud

See the onboarding section in SonarCloud analysis .

Customize GitHub settings

By placing an .asf.yaml file one can customize certain GitHub settings like label, features and merge options.

Creating links to Git commits

To quickly create links to Git commits in JIRA a script such as the one below can be used:
#!/bin/sh -e
if [ $# -eq 0 ]; then
hash=$(git rev-parse --short ${commit})
base=$(git remote get-url origin)
echo "[commit ${hash}|${url}]"
  • No labels