Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create an initial documentation page for Dependabot #40

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Create an initial documentation page for Dependabot #40

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions .github/dependabot.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
= Dependabot

WARNING: This page is under development. Contributions are welcome!

In the Jenkins project we use https://dependabot.com/[Dependabot] for automating dependency updates in our repositories.
It includes Java/Maven, Java/Gradle, JavaScript, Docker and other package manager types.
Jenkins project repositories currently use the Github-native Dependabot and the deprecated standalone versions,
migration is pending.
Comment on lines +7 to +8
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Jenkins project repositories currently use the Github-native Dependabot and the deprecated standalone versions,
migration is pending.
Jenkins project repositories currently use the Github-native Dependabot and the deprecated standalone versions (migration is pending).


This page documents jenkins-specific recommendations for using Dependabot in the Jenkins repositories.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This page documents jenkins-specific recommendations for using Dependabot in the Jenkins repositories.
This page documents Jenkins-specific recommendations for using Dependabot in the Jenkins repositories.

Please refer to the official https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/keeping-your-dependencies-updated-automatically[Dependabot documentation] for details and examples.

== Documentation links

* https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/enabling-and-disabling-version-updates#enabling-github-dependabot-version-updates[Enabling Dependabot in your repository]
* https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/configuration-options-for-dependency-updates[Configuration file]
* https://github.blog/2020-06-01-keep-all-your-packages-up-to-date-with-dependabot/#moving-forward-from-dependabot-com-and-dependabot-preview[Moving to GitHub-native Dependabot from Dependabot.com and dependabot-preview]

== Usage recommendations for Jenkins plugins (Maven)

* Make sure that you do not disable Maven Enforcer Plugin when using Dependabot.
Otherwise there will be a high risk of unnoticed dependency and binary compatibility conflicts.
* It is **not recommended** to automatically update Jenkins core to the most recent versions, because it will prevent LTS users from using them.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Huh?

First of all, it would be fine to enable Dependabot on Jenkins core, so long as you picked an appropriate pattern: *.*.* or whatever the syntax is. (And even if you left the version to float freely to weeklies, this would not prevent LTS users from running your plugin—only the latest versions of your plugin, released after the last LTS branching point.)

But anyway, as far as I know it does not work; Dependabot does not grok that

<jenkins.version>2.176.3</jenkins.version>

is fixing the version of an artifact defined in a parent POM and is thus eligible for upgrade. It only looks for artifacts defined in the literal pom.xml as far as I understand it.

You say you can configure a filter to prevent Dependabot from upgrading Jenkins core, but the plugin example does not do so.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense. I'd rather keep the config file smaller if this is something Dependabot does not do (anymore) I think.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BTW, the example to simply ignore Jenkins Core updates would be https://github.com/jenkinsci/configuration-as-code-plugin/blob/0aff116d84574d8880530176269edaef6bc8b023/.github/dependabot.yml#L8-L11.

See https://www.jenkins.io/doc/developer/plugin-development/choosing-jenkins-baseline/[this page] for baseline selection recommendations.
You can configure a filter to prevent Dependabot from updating Jenkins core versions (see the examples)
* There is a https://github.com/jenkinsci/bom/[Plugin Bill of Materials] which defines versions for many most used plugins.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* There is a https://github.com/jenkinsci/bom/[Plugin Bill of Materials] which defines versions for many most used plugins.
* There is a https://github.com/jenkinsci/bom/[Plugin Bill of Materials] which defines versions for many plugins in common use as dependencies.

If you do not have a strong version requirements, it is recommended to supply the versions through BOM instead of letting Dependabot manage each dependency version.
It also reduces likelihood of upper bounds conflicts discovered by Maven Enforcer Plugin.
* Be careful with library dependencies, especially for popular utility libraries.
Requiring recent versions may sometimes cause binary conflicts with other plugins and the core.
Comment on lines +29 to +30
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is threatening yet so vague as to be useless. If you are going to say anything, at least link to https://www.jenkins.io/doc/developer/plugin-development/dependencies-and-class-loading/#bundling-third-party-libraries

And the example link is to an obscure plugin that

  • Includes library dependencies like asm few plugins would use.
  • Is blocking updates to the jackson2-api plugin, as well as other plugins defined in the bom.

Better pick a different example.


== Jenkins component Configuration Examples

* https://github.com/jenkinsci/jenkinsfile-runner/blob/master/.github/dependabot.yml[Jenkinsfile Runner] - Java/Maven example
* https://github.com/jenkinsci/autograding-plugin/blob/master/.github/dependabot.yml[Autograding Plugin] - Java/Maven configuration for a plugin, with ignore filters

NOTE: More examples will be added when project migrate to a GitHub-native Dependabot implementation with a v2 configuration format
(`.github/dependabot.yml` files and configurations in GitHub project settings).
Comment on lines +37 to +38
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is worth holding off on docs until we have better, more typical examples.

The canonical example is far simpler: https://github.com/jenkinsci/archetypes/blob/3e5a8cc4f208c51203cac20b882ccfcba397c657/common-files/.github/dependabot.yml


== References

* https://groups.google.com/forum/#!topic/jenkinsci-dev/XMllKuWLO_8[Developer Mailing List thread] - For discussion and proposals
* https://speakerdeck.com/onenashev/joker-2019-tame-your-dependencies-with-dependabot[Tame your dependencies with Dependabot!] -
presentation about Dependabot adoption in the Jenkins project made in Oct, 2019.
** Note: this presentation uses the old Dependabot version with obsolete configuration formats
* https://docs.google.com/document/d/1hRrH8PSCswBQgY_Q-7eHCHCVZHJOl4XgQQCswdUmpKY/edit?usp=sharing[Dependabot Evaluation notes in Jenkins] - Additional random thoughts and takeaways