...
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.
In practice, we have found that:
- for contributions which require no additional fixes we should use the 'Rebase and merge' workflow
- for contributions which require fixes
- in case of a single logical commit we should use the 'Squash and merge' workflow to create a single commit. This creates a fast-forward merge, so no merge commit.
- in case of multiple separate commits we should ask the reviewer to amend the original commits with the fixes and force-push the branch that is the source of the PR
- using the 'merge' button for PRs should be the exception
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.
...
See a recent example below
Note | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
Sling uses the default branch name
See also the discussion from
|
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.
...
Reference: https://help.github.com/en/articles/splitting-a-subfolder-out-into-a-new-repository
Maven SCM settings
The SCM settings from the pom.xml file are read by various tools, but most often used by the maven-scm-plugin
when releasing. We set the connection and developerScm settings to reference the ASF-maintained gitbox service, but use GitHub for the URL since it offers a better browsing experience and receives special treatment from some tools, such as renovate.
Code Block | ||||
---|---|---|---|---|
| ||||
<scm>
<connection>scm:git:https://gitbox.apache.org/repos/asf/sling-org-apache-sling-$MODULE.git</connection>
<developerConnection>scm:git:https://gitbox.apache.org/repos/asf/sling-org-apache-sling-$MODULE.git</developerConnection>
<url>https://github.com/apache/sling-org-apache-sling-$MODULE.git</url>
</scm>
|
Update the repo manifest
Regenerate the default.xml manifest form the sling-aggregator repo using groovy collect-sling-repos.groovy > default.xml
.
Update local Sling repo checkout
Execute the following comman in the root of the Sling repo checkout
Code Block | ||||
---|---|---|---|---|
| ||||
$ repo sync -j 16
$ cd ${NEW_REPO}
$ git checkout master |
Boilerplate files
Ensure that at a minimum the repository contains the following files:
...
Most of the files can be copied from any repository. We'll use org-apache-sling-api
as an example.
Code Block | ||||
---|---|---|---|---|
| ||||
$ cd org-apache-sling-api $ cp CODE_OF_CONDUCT.md |
...
CONTRIBUTING.md Jenkinsfile LICENSE .gitignore ../${NEW_REPO} |
Generate a default .asf.yaml
file and update it, if applicable:
Code Block | ||||
---|---|---|---|---|
| ||||
$ cd aggregator
$ groovy ./scripts/update-asf-yaml.groovy ../org-apache-sling-commons-metrics-prometheus/ |
See Git
...
- .asf.yaml features for more details:
- tags: include initially
sling
andjava
(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
Badges
The sling-aggregator/add-badges.sh 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.
Code Block |
---|
$ cd aggregator $ groovy ./addgenerate-project-badges.shgroovy ../ ${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 dev@kibble.apache.org about itSee Repository analysis with Kibble .
Onboard to SonarCloud
See the onboarding section in SonarCloud analysis .
...