Why store package version changes in package?

[martindsouza]

From https://github.com/insum-labs/plsql-and-sql-coding-guidelines/blob/master/docs/3-coding-style/coding-style.md it's recommended to store all the package changes (i.e. comments about the package changes) in the version function. Why even have this? My thoughts on why not:

• Redundant to what should be in source control
• Requires additional work from devs to write both in there and in version control
• Will lead to missed comments. I've seen this done in several environments and in all the cases devs forget (rightfully so) to update the version changes as they've already commented in the code commit message.
• If devs are looking at changes to a package using the change log in their version control system is better

Overall this problem is solved with proper version control so I don't see value in adding additional work for no value.

[rimblas]

@martindsouza I agree. I think this only makes sense when there's no source control and you work by editing packages directly in the DB, which you shouldn't do at all anymore in 2020.

[RichardSoule]

Not every customer is using version control, and this works.

Also, using REST services that query DEV/TEST/QA/PROD you can easily report the differences in versions between different environments.

[rimblas]

@RichardSoule if you feel strongly about this, let's move it to its own guideline document and an appropriate "tip", it doesn't belong in the Coding Style.

Could you work on that?

[RichardSoule]

I'd like to get Anton's feedback. This is something that he's done for a very, very long time (and, as you point out, it could be 'out of date'), but I do think it adds value.

Very often commit comments are 'a bit too vague', and having information directly in a package allows developers (maybe on other projects) and/or DBAs who don't have access to the version control system to 'see what happened when'.

[martindsouza]

@RichardSoule If we are going to keep this I'd prefix the entire section as "Only if version control is not present".

[RichardSoule]

@martindsouza How would you address the 'report of all environments and the versions they are actually running' if you only have version control?

[martindsouza]

@RichardSoule Tags. Though I currently don't do a great job of this it's as simple as keeping a matrix of environment vs tag (most release tools keep track of this)

Simple form is:

env	tag
dev	NA
test	1.1.0

Note: dev is Not Applicable as it's active development

Either way don't know why a REST call would need to know the version of a package it's referencing.

[ainielse]

I think there are two items here... the function "package_version" and the comments within that function.

Having the package_version function has been very helpful when I receive a call from someone (who I haven't heard from in years) that says, "We're using the filing document system and seeing this issue." They installed it as a package app 4 years ago, and now have a question. I'm able to quickly retrieve a list of all the packages and what version they are running because we have a REST service that provides that info.

The comments are less directly helpful in that scenario, but, as opposed to a Git checkin, it's on every package, not just at the commit level.

So, personally, I don't find it redundant or time consuming. I do find it helpful. In the spirt of "if you don't like it, don't implement it," I would just add some sort of optionality to it in the documentation.

[RichardSoule]

Also, there are many situations where DBAs don't have access to the Git repository, but they do have access to the database.

So, if we said anything, we could say something like:

"If you are using version control and everyone who would ever look at the package source, including the DBAs, developers on other projects, etc., has access to the version control system, then you could find this redundant. Instead, the comments section could just include a direct link to the version control system."

[rimblas]

@ainielse do you have this REST call and report working somewhere that you can show us? Now I'm curious.

@RichardSoule DBA's not having access to the repository is not a normal real-life thing. This is specially not true if they are, like in many places, involved in deployments. And if the version is not correct, where do you think they will need to go to get the correct version?

[martindsouza]

@RichardSoule @ainielse All good points but very situational for specific given conditions. Given all the feedback would it help to have a different section for situational guidelines. The purpose is to not clutter the core guidelines.