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.

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

Stop including version numbers in file names #246

Closed
ahouseholder opened this issue Jun 16, 2023 · 3 comments · Fixed by #247
Closed

Stop including version numbers in file names #246

ahouseholder opened this issue Jun 16, 2023 · 3 comments · Fixed by #247
Assignees
Labels
documentation Improvements or additions to documentation enhancement New feature or request environment Project environment, deployment, CI, etc.
Milestone

Comments

@ahouseholder
Copy link
Contributor

ahouseholder commented Jun 16, 2023

Over in #238 I came across a concern about the use of version numbers in file names.

  • .csv files in data/csvs have strings like v1, v2, v2_1
  • .json files in data/schema have strings like v2.03
  • .json files in ssvc-calc have strings like v2.0.3, v2.1.0

Regardless of our versioning strategy, I propose that we eliminate version numbers from file names.

Rationale:

  • Either we strictly enforce that every edit to a file must change the file name or a file will be edited more often than its name will change.
  • This will mean that over time the repository will contain multiple versions of a file named foo-vX.Y.Z.json, which has side effects, including:
    • the version string in the name is actually misleading because the file changed but the identity defined by the version string did not
    • sometimes the content of that file will serve as the basis for a new file foo-vA.B.C.json and foo-vX.Y.Z.json will be removed.
    • when changing the file name, a developer may be concerned about preserving the X.Y.Z version and have the urge to create an archive folder or some such
    • while the preservation/conservation concern is warranted, by creating archive files we'd be double-version-controlling. One using git, the other using human copy-to-folder process.
  • I'd rather trust git to be consistent in this process.

The alternative I'm proposing is that we remove version numbers from file names and let the git commit history be the canonical source for older versions of those files. So if you want to see the foo-v1.json, go to the v1 tag in the history and get it. My preference is to let git be git, and avoid overthinking version strings in file names.

@j---
Copy link
Collaborator

j--- commented Jun 21, 2023

I think this makes sense.
How do we use semver to reference versions of the trees etc?
One option is that each suggested tree inherits the version of SSVC? I didn't address this in https://github.com/CERTCC/SSVC/blob/main/doc/style-guide-how-to.
If we use SemVer, then I would imagine major versions break backwards compatibility by changing decision point definitions, changes to scope or other fundamental definitions, etc. Minor versions are meaningful changes to recommended decision trees? And then bug fixes are everything else?
Does this mean we need the version number represented within the file or file metadata somehow?

@ahouseholder
Copy link
Contributor Author

I spawned #252 to capture @j--- 's comment about versioning trees as a separate issue. I don't want to lose it when we merge #247 and resolve this (#246) issue.

@j---
Copy link
Collaborator

j--- commented Jun 29, 2023

Thanks. With #252 open, I think it's OK to go ahead and rename the files in order to close this issue.
@sei-vsarvepalli or @cgyarbrough just need to review #247

@ahouseholder ahouseholder added this to the SSVC v2.1 milestone Jul 5, 2023
@ahouseholder ahouseholder added documentation Improvements or additions to documentation enhancement New feature or request environment Project environment, deployment, CI, etc. labels Mar 1, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request environment Project environment, deployment, CI, etc.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants