Skip to content
This repository has been archived by the owner on Jun 9, 2023. It is now read-only.

Suggestion to create regular tagged commits #449

Open
NorthDecoder opened this issue Mar 10, 2021 · 6 comments
Open

Suggestion to create regular tagged commits #449

NorthDecoder opened this issue Mar 10, 2021 · 6 comments
Labels
Discussion Ideas, feature requests, views on features. Anything which is a discussion. Meta Security

Comments

@NorthDecoder
Copy link
Contributor

A view from the peanut gallery. I have not been able to contribute much, however I have regularly followed the commentary and issues. One comment that worries me has been repeated a couple of times is something like "when we release our MVP at 1.0". The way I literally see the commit network on Github is as a series of releases to the public. The project is open to anyone who wants to look at or clone the code to try it. Whether we like to admit it or not, it is already released.

A few weeks ago, I tried to find the data definition language (DDL) feature from early on in the project and after hunting and pecking through each commit I realized that I was not going to find it in a reasonable amount of time.

This example of my search highlights a lack of commit strategy I think could create potential headaches for the project developers going forward, which is why I am suggesting that on some schedule a project admin tags a commit on master and gives it some responsible version name, number or date or whatever. That way Github will ball up everything in the project and make a zip file snapshot of the project to be readily inspected, tested, shared etc.


Current discussions about bumping to the next major version of nodejs is another example of when this project could reasonably be expected to have a tagged commit noting the major changes.

@allella
Copy link
Contributor

allella commented Mar 10, 2021

Thanks for the suggestion. I'm sure we can tag releases when we have something folks feel is worth tagging.

At this point, everyone has been iterating on the latest code and I can't recall anyone needing to jump back to an earlier copy, which I assume they could do using a commit hash in the logs.

Is there any guidance on when to start tagging 0.1.0 release, or some such.

Also, the out of date schema can be seen in the CONTRIBUTING.md under the Database section by expanding a collapsed area. I have PR #448 open to clean up the CONTRIBUTING.md so if you have time to contribute, then feel free to run through this copy and suggest improvements. It now breaks Running the Application into Docker-mode and Manual-mode, since we have a mix of how contributors are running their dev environment.

Also, we could use help getting a schema that's auto updated. Schemaspy is the suggested direction and we need someone with experience to make that happen on #54.

@allella
Copy link
Contributor

allella commented Mar 10, 2021

Also, here's an out of date Schemaspy schema from #54 (comment)

@NorthDecoder
Copy link
Contributor Author

NorthDecoder commented Mar 12, 2021

Chapter-commit-tag-proposal

A suggestion for choosing to begin using
commit-tags for Chapter in synchronization
with the ecosystem cadence

Tag syntax options

  • Semantic Versioning semver

    • for example: major.minor.patch
      • implies that we know by feature and API testing
        when there are breaking changes at the major level.
  • Calendar Versioning calver

    • for example ubuntu style: 4.10 (year.month)
      • assigns significance to a date, but does not
        necessarily imply breaking changes.
  • hybrid

    • for example: 2021.Q1.99 (year.quarter.patches)
      • allows for both calender and knowledgeable changes.

Benefits

  • zipped file snapshot - Commit tags are used by Github
    and GitLab to create zipped files of the entire project
    that can be downloaded or referenced online with the
    branch compare tool.

  • known good reference points - Tagged commits can be used
    if the latest commits turn out to not work in a certain
    environment, then the last known working version can be re-installed.

  • exact reference - Issue writers can refer to a commit tag
    so that maintainers could attempt to replicate the writers environment.

  • regular backups - Is someone backing up the project offline?

Comparisons

Looking at the tags for several of the Chapter dependincies,
Postgresql, NodeJS, typeorm, pg, and next

  • 'Postgresql' and 'NodeJS' use a combination of version numbers
    related to a date based roadmap.

  • 'typeorm' uses a sequence of numbers 0.2.23, 0.2.24, 0.2.25
    etc.

  • 'pg' and 'next' appear to apply semantic versioning with
    detailed commentary on breaking changes, however 'next' adds
    the word 'canary' in their intermediate patch tags.

For reference look at the tag history for 2020

chapter-commit-tag-proposal-2020

Then look foward at 2021, 2022, 2023, 2024

chapter-commit-tag-proposal-2021

chapter-commit-tag-proposal-2022

chapter-commit-tag-proposal-2023

chapter-commit-tag-proposal-2024

Conclusion

  • We know the planned roadmap for NodeJS and Postgresql and
    we can plan ahead for the timing of those changes.

  • Choosing a goal of maintaining Chapter dependency versions
    updates
    with an annual-plus-quarterly milestone commit tag cadence
    will capture the significant ecosystem changes. Adding a patch at the
    end of the tag will capture Chapter feature improvements within the
    quarter.

  • For example, tags for dependency update milestones in 2021
    on the first Wednesday of each quarter, would be something
    like:

      DATE          TAG
      Jan 6, 2021 - v2021.Q1.01
      feature       v2021.Q1.02
      feature       v2021.Q1.03
      Apr 7, 2021 - v2021.Q2.01
      Jul 7, 2021 - v2021.Q3.01
      Oct 6, 2021 - v2021.Q4.01

@allella
Copy link
Contributor

allella commented Mar 12, 2021

Thanks for the well described options.

I'd see the tags being more useful once we're into or approaching an alpha. Right now the app is going to be in flux and we don't really have stable points. Though, if you feel we should start tagging at reasonably stable points, like with semver, then that's what I've most familiar with.

At this point, we need commits more than tags. However, if you want to lead the charge on a tags system, then we'd be glad to have your leadership on this task.

@NorthDecoder
Copy link
Contributor Author

NorthDecoder commented Mar 14, 2021

@allella I see what you mean about commits, a tag only has significant meaning the project participants assign to it. Here is an example of suggested meanings assigned to a tag.


Quarterly milestone goals

Generic

[ ] Update chapter version numbers in code to match the pending milestone version

[ ] Security version updates

  • npm recommendations
  • dependabot recommendations
  • snyk recommendations

[ ] Update dependency versions

[ ] Remove unused packages

[ ] No lint errors

[ ] No test failures

[ ] Following CONTRIBUTING instructions results in successful builds in the master branch for:

  • docker mode

  • manual mode

[ ] Create next project milestone


Specific features

[ ] Add CI/CD build pipeline test badge to the README

[ ] Add a branch named stable


Workflow

The workflow might look something like this.

About three weeks before the quarterly milestone some trusty volunteer would fork and then create a branch called for example RC-2021.Q2.00. There would be no more features added to this RC branch. The proposed version upgrades would be added and linted, tested and built as suggested in the goals above. When all the lints, automated and manual tests are completed, then the last commit on that branch would be tagged with the name for example 2021.Q2.00 and merged with with the branch stable and a pull request made to the master repository.

Finally the branch stable would be merged back into master, to capture security and dependency updates, ( hmm... as well as the latest stable version number in the project code, that would need to be updated to reflect the in-flux master branch. ) and a pull request would be made to the master repository as well.

At this point a video could me made to capture project highlights in the stable branch.

To maintain project momentum, feature changes would still be allowed on the master branch, which would continue to be the default branch.

@allella
Copy link
Contributor

allella commented Mar 15, 2021

Thanks again for the detailed suggestions.

I'm still of the mind this is all best for seeding a future conversation once we have something worth tagging. We're still a good 6 months from even having something we might share with testers.

As it is, progress is slow and until we get an app that renders and looks useful, I'm not sure we'll have much need to tag it as a relatively stable point in time.

Also, since this is not actively deployed, I'm imagining we can bring all the packages up to date for security and features as we get closer to identify a taggable point.

We expect Fran to be active in the next 1-2 weeks and I'm sure he'll have thoughts and much of the progress has been dependent on his commits.

@allella allella added Discussion Ideas, feature requests, views on features. Anything which is a discussion. Security Meta labels Mar 15, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Discussion Ideas, feature requests, views on features. Anything which is a discussion. Meta Security
Projects
None yet
Development

No branches or pull requests

2 participants