tools.build/write-pom docstring could be clearer about prohibited keys

Question

The tools.build/write-pom docstring advises which keys not to include for pom-data:

:pom-data - vector of hiccup-style extra pom top elements to include when
  :src-pom is :none or the source pom.xml does not exist:
   [[:licenses
     [:license
      [:name \"Eclipse Public License 1.0\"]
      [:url \"https://opensource.org/license/epl-1-0/\"]
      [:distribution \"repo\"]]]
    [:organization \"Super Corp\"]]
  The pom-data MUST NOT include:
    :modelVersion, :packaging, :groupId, :artifactId, :version, :name,
    :deps, :repositories, :build, or :scm

"MUST NOT include" list might be a bit stale? If we are not working from a pom.xml, we can include, for example, :scm.

I noticed :scm usage on next.jdbc, and pinged Sean Corfield about it.
He was kind enough to dig up an old Slack thread.

It was a bit confusing then, and it is still confusing now.
In the spirit of being helpful to the community, I'm raising this issue to consider a review of the write-pom docstring.

I'd recommend a clearer version, but I'm unsure of what the rules really are.

Answer 1

iirc, there is an explicit :scm argument to write-pom (pre-dates :pom-data) which was the reason for not putting it in :pom-data.

Comments

Thanks for the reply.

Yeah there is an `:scm` option:

    :scm - map of scm properties to write in pom
           keys:  :connection, :developerConnection, :tag, :url
           See: https://maven.apache.org/pom.html#SCM for details

And as a good rule follower, I've used that.

But I think it is also fine to use `:scm` under `:pom-data` as illustrated by next.jdbc's usage?

---

Yeah, I think these things fall into a few categories that could maybe be clearer: 1) stuff provided by the gen template, 2) stuff computed into the template, and 3) stuff that has some other path. #1 is bad and will cause an invalid pom, #2 will get replaced so won't be used and #3 is probably ok (:scm).