nf-core / website

Code and files for the main nf-core website.
https://nf-co.re
MIT License
69 stars 196 forks source link

Update semantic_versioning.md #2842

Open pinin4fjords opened 2 weeks ago

pinin4fjords commented 2 weeks ago

Better outline semantic versioning, and try to persuade users to bump major versions when they should.

@netlify /docs/guidelines/pipelines/requirements/semantic_versioning

netlify[bot] commented 2 weeks ago

Deploy Preview for nf-core-docs ready!

Name Link
Latest commit 61e6972a59e80739825d1dcfba8e764a29993982
Latest deploy log https://app.netlify.com/sites/nf-core-docs/deploys/672cb19753928f0008b5c112
Deploy Preview https://deploy-preview-2842--nf-core-docs.netlify.app/docs/guidelines/pipelines/requirements/semantic_versioning
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

netlify[bot] commented 2 weeks ago

Deploy Preview for nf-core-main-site ready!

Name Link
Latest commit 61e6972a59e80739825d1dcfba8e764a29993982
Latest deploy log https://app.netlify.com/sites/nf-core-main-site/deploys/672cb19729aaa600086daf8c
Deploy Preview https://deploy-preview-2842--nf-core-main-site.netlify.app/docs/guidelines/pipelines/requirements/semantic_versioning
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

jfy133 commented 2 weeks ago

Can you link to this page on the release docs too @pinin4fjords ?

pinin4fjords commented 2 weeks ago

@nf-core-bot fix linting

jfy133 commented 2 weeks ago

I like this. I also asked Seqera AI and here's what it gave:


    Patch Release (1.4.4):
        Fixing a typo in the pipeline documentation or help messages
        Updating a dependency to patch a security vulnerability without changing functionality
        Correcting a minor bug in result reporting that doesn't affect the actual analysis results
        Optimizing a process to use less memory or run faster without changing its inputs or outputs
        Fixing a minor issue in the pipeline's error handling or logging

    Minor Release (1.5):
        Adding support for a new input file format without changing existing format support
        Introducing a new optional quality control step that doesn't affect the main analysis
        Adding a new visualization option for existing results
        Implementing a new caching strategy that improves performance but doesn't change results
        Adding support for a new cloud computing platform without affecting existing platform support

    Major Release (2.0):
        Changing the default behavior of a core analysis step
        Removing support for an outdated file format or tool
        Restructuring the pipeline's output directory organization
        Implementing a new parallelization strategy that requires users to specify different resource allocations
        Changing the pipeline's command-line interface structure
        Modifying how configuration files are structured and processed
        Upgrading to a new major version of Nextflow that requires changes in how users interact with the pipeline

This is good for extra examples, but IMO some the examples are maybe too generic: e.g.

    Changing the pipeline's command-line interface structure

I think we should make it more explitily/modular using our language (like as I've suggested) as it'll be more likely be picked up by a developer when skimming the text.

Sort of like 'Have you changed a parameter name?' is going to be more eye catching 'yes I did that' than just 'did an interface change'.

What do others think?

mahesh-panchal commented 2 weeks ago

Having it more tuned to our use case is definitely going to help. It's not an easy task though because words can mean different things to different people resulting in some being confused and others going "yeah, that's clear as day - I did that".