add versioning

[cbm755]

Is this project versioned? In particular, does the mbx binary have a version number?

If not and you'd like it to, I could send a PR which add a version number, probably using Semantic Versioning.

[rbeezer]

No versioning yet. Not really ready to manage all that, since it still feels like we have major holes to plug, and various changes planned.

For mbx what would you call the "public API"? The command-line arguments, or the function signatures (which I want to split off to encourage re-use)?

The functions here all apply XSL stylesheets to source files, and those change much more often.

Depending on how often version numbers need to change, this might be a good place to start experimenting.

[cbm755]

Not really ready to manage all that, since it still feels like we have major holes

You can leave it at 0.0.1.dev until you're ready. I'll send a MR/PR for your consideration.

---

Personally I would think about the command-line arguments as the "API". But a basic premise of Semantic Versioning is until you hit that magic "1.0.0", you make no promising about API stability anyway.

A good rule of thumb is "0.1.0" bumps to "0.1.1" for minor non-API breaking. and to "0.2.0" for API breakage.

Versioning of XSL: no idea, maybe later those get versioned separately for the scripts but for now I'd keep it simple with just have a global version number.

[davidfarmer]

PreTeXt relies on some JavaScript and some CSS, each of which have their own versioning, and well as on 3rd party resources, such as MathJax.

Any instance of the PreTeXt XSL uses a specific version of those other resources. For example, as of this moment, an HTML file generated from PreTeXt will contain

< script src="https://pretextbook.org/js/0.13/pretext.js" >< /script >

How does PTX versioning interact with the other versioning?

On Sat, 16 May 2020, Colin B. Macdonald wrote:

  Not really ready to manage all that, since it still feels like we have major holes

You can leave it at 0.0.1.dev until you're ready. I'll send a MR/PR for your consideration.

---

Personally I would think about the command-line arguments as the "API". But a basic premise of Semantic Versioning is until you hit that magic "1.0.0", you make no promising about API stability anyway.

A good rule of thumb is "0.1.0" bumps to "0.1.1" for minor non-API breaking. and to "0.2.0" for API breakage.

Versioning of XSL: no idea, maybe later those get versioned separately for the scripts but for now I'd keep it simple with just have a global version number.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, orunsubscribe.[AABTULCXB224EACTFTET7HLRR3YFJA5CNFSM4M7IDHU2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNM VXHJKTDN5WW2ZLOORPWSZGOEWEHP6A.gif]

[cbm755]

I assume these other tools come from outside your repo? I think (but I am not an expert) that usual practice would be something like a requirements.txt file (and a tool like virtualenv or Docker) to pin the versions of the other packages / tools / etc at known good (tested) versions.

[davidfarmer]

Once we complete the renaming of mathbook to pretext, it will go under

https://github.com/PreTeXtBook

which already has the CSS and JavaScript for PreTeXt. Not sure if those should all be in the same repository.

On Sat, 16 May 2020, Colin B. Macdonald wrote:

I assume these other tools come from outside your repo? I think (but I am not an expert) that usual practice would be something like a requirements.txt file (and a tool like virtualenv or Docker) to pin the versions of the other packages / tools / etc at known good (tested) versions.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub, orunsubscribe.[AABTULCWZILEZSYGPYIDFLDRR4Z4XA5CNFSM4M7IDHU2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNM VXHJKTDN5WW2ZLOORPWSZGOEWEOAOI.gif]

[sean-fitzpatrick]

I was wondering this yesterday: is it feasible to ship PreTeXt as a Docker image (or even something like Ubuntu's "snap" packages)?

We're seeing this with things like Asymptote images: to get everything working right, we need a very recent version of Asymptote. And that, in turn, needs the latest version of dvisvgm, and so on.

Docker could in principle provide a one shot installation of PreTeXt with all necessary helper applications, all at the right versions, even if someone is running a slightly older OS.

[cbm755]

@sean-fitzpatrick Probably. @arechnitzer and I are doing all that for another project so we can apply that knowledge here too.

[sean-fitzpatrick]

Ah, yes. I hope the PLOMmery is going well.

[StevenClontz]

I was wondering this yesterday: is it feasible to ship PreTeXt as a Docker image (or even something like Ubuntu's "snap" packages)?

We're seeing this with things like Asymptote images: to get everything working right, we need a very recent version of Asymptote. And that, in turn, needs the latest version of dvisvgm, and so on.

Docker could in principle provide a one shot installation of PreTeXt with all necessary helper applications, all at the right versions, even if someone is running a slightly older OS.

I think there are two levels to this. I think a large chunk of PreTeXt's functionality can be captured in pure Python to produce LaTeX and HTML output, so authors can quickly get up and writing with a pip install pretext && pretext new "My Great Book". This is much quicker than setting up Docker, and I think it's important that we have a very quick path to get interested new authors started.

Then, we can also capture a "full" installation of PreTeXt in a Docker image. This could include things like TeXLive, Asymptote, etc.