Allow cookbook to pair build version with Arrow release version

[thisisnic]

As more features are added to Apache Arrow, we might want to build versions of the cookbook that are relevant to that release.

I'm not sure what a good strategy would be in terms of adding content, e.g. is the main branch the latest version, and we create branches for releases, and then cherry-pick any commits which are relevant to multiple cookbook versions? And how many versions to have, in terms of major/minor releases?

[westonpace]

So I thinking this over and had a couple of thoughts.

First, it would probably be good if each implementation had the freedom to adopt a strategy that works for them. We don't want to discourage an implementation from getting started by setting a high bar.

Second, I think there are a few levels to choose from:

1. No guarantees. Each build of the cookbook is run against the latest (source or nightly) build of Arrow. This is the only testing that is done. New features are added immediately.
2. One version of recipes, multiple versions of Arrow. There is only one cookbook. For every recipe the cookbook would need to provide which version of Arrow it supports. CI would then run multiple passes with multiple builds of Arrow (e.g. one CI run might test against 3.0 and 4.0 and 5.0. Each pass would verify more and more recipes.
3. Multiple versions of recipes, multiple version of Arrow. This is similar to option 2 but a cookbook could have the same recipe multiple times for multiple versions (e.g. this is how you do XYZ on versions 3-5 and this is how you do XYZ on versions 6+). The website would need some kind of version selector dropdown. The cookbook would need #ifdef type capabilities to pick which recipes to run on which versions of Arrow. CI would still need multiple passes of Arrow.

The one approach I think we should NOT do is:

Every build we test against the latest released version of arrow and new recipes can only be added after the particular feature has been released. I feel this will discourage Arrow developers from contributing to the cookbook as they add new content. By the time Arrow has released they might not be so interested in the feature anymore or they may have forgotten details.

[thisisnic]

First, it would probably be good if each implementation had the freedom to adopt a strategy that works for them...

Agreed, thanks for pointing this out!

Thinking specifically about the R cookbook then:

1...

I don't think this would be suitable for the R version of the cookbook, as the API is growing in features at the moment, and it may be the case that users work for organisations which aren't going to let them keep up with the 3 monthly release cycle - this could be confusing when readers are faced with content which doesn't work for them.

2...

I thought about this - it would make reordering content complicated, and I don't know if that's an issue or not. I don't think it'd be too hard to implement though.

3...

This approach sounds closer to what I was thinking, but could be tricky to implement in terms of integrating it with bookdown.

The one approach I think we should NOT do...

Yeah, agreed, I think we need to be able to have something for the current version (nightlies)

How about this approach:

4. a modified version of multiple versions of recipes/multiple versions of Arrow:

• instead of a dropdown, multiple versions of the cookbook are built, and so the URL for the main page is e.g. whatever/arrow-cookbook/r/5.0.0/index.html. Therefore, the differing functionality is kept separate to prevent confusing readers.

• the content relating to the upcoming release is merged into main, which builds against the nightlies, and once a release has been done, that version of the cookbook gets its own branch.

• admittedly, there is a bit of extra work when a new PR is merged, as it would be necessary to create additional PRs to add the content to previous versions if the recipe works on those. I suppose this extra workload might be higher at first, but as time goes on and more recipes are added, new content is more likely to be applicable only to new features rather than existing ones

• with each release, we add a new CI job for that release. I suppose a potential issue is this getting potentially huge, but we could choose to adopt a strategy like "freezing" older cookbooks so that new recipes are never added to them and so they don't need to be rebuilt, and only building against the most recent patch for each major release.

[westonpace]

I think that could be a workable solution. I do think you will end up with a lot of cookbooks and then if you find a grammar issue for example you have to fix it in several places. That being said, you could always have a limit on how many versions of Arrow we support. For example, only keep the cookbooks for 2 years of Arrow versions or something. I don't plan on going quite that far with the C++ cookbook anytime soon although maybe someone else will want to. Do you think the different cookbooks need to align on how they approach this? I was hoping for C++ to be able to do something like this...

BEGIN_RECIPE("Xyz", 3.0.0) {
  DoThingOldFashionedWay();
}
BEGIN_RECIPE("Xyz") {
  DoThingNewWay();
}

This would then use the older method for versions <= 3.0.0 and the newer method for all other version. However, I could compile this into multiple cookbooks as easily as a single cookbook with dropdown selectors.

[jorisvandenbossche]

I think that could be a workable solution. I do think you will end up with a lot of cookbooks and then if you find a grammar issue for example you have to fix it in several places. That being said, you could always have a limit on how many versions of Arrow we support.

The question is then indeed how long we intent to maintain the "older" cookbooks? Because it sounds a maintenance burden to actively maintain multiple versions ..

That might be a good reason, while the content is still growing in a faster pace, to not yet have separate versions.

If it's mainly about recipes that use new features that are not yet available in older versions, then for now we could maybe also include some standard text like "Requires Arrow x.x" where needed.

[thisisnic]

Do you think the different cookbooks need to align on how they approach this?

Not at all, I'd be actively opposed to that as it'd be unnecessary. I think that the user bases may be vastly different for different Arrow implementations and this approach would be totally unnecessary for most. I'm basing my thinking off an assumption I'm making that the R package will have 2 main groups of users:

1. People building things on top of Arrow, those who are likely to use the lower-level functionality
2. People who are just using it for data analysis; in the R implementation they'd be mainly using the read/writing functions and dplyr syntax and not going anywhere near the lower-level stuff

I think all Arrow implementations will have people from group 1, but R will have a higher proportion of people from group 2. My concern here is that it's very common in industry to encounter folks who are locked to certain package versions because of the strategy their IT department has chosen to handle R package management.

The question is then indeed how long we intent to maintain the "older" cookbooks? Because it sounds like a maintenance burden to actively maintain multiple versions ...

I think there are lots of options for managing the maintenance here sensibly (e.g. freezing previous versions after every release and only updating them if someone cares enough to submit a PR at which point that CI job can run and that version updates, only going back ~6 major releases).

That might be a good reason, while the content is still growing in a faster pace, to not yet have separate versions.

Sure - there'd only be 1 version right now anyway as I wasn't looking at writing content for Arrow versions before 5.0.0.

I'm going to nudge some more of the R folk for their opinion, as I'm a bit torn about what the best answer is for the R implementation here.

[nealrichardson]

I would expect something similar to how we handle the arrow library docs (or rather, how we should do them since we still don't do this): We host the dev version at /latest/, and at release time, that gets moved to /x.0.0/ and a new /latest/ is created. I don't think we should worry about maintaining cookbook recipes for versions older than the current release, they just are a static snapshot of how things worked then.

[jonkeane]

As a slight extension of what Neal is proposing (and adding something Weston mentioned) we could take the approach of not backporting/maintaining old versions of the cookbook when we release a new version of arrow (they are kept with the exact same content that they had before). And also (especially while we are actively expanding that coverage of the cookbook) we mention what version a feature became available in. That way if we do add a long-standing feature to the cookbook, someone could look at the latest cookbook and see "oh this is available starting in version 2.0, I'm on version 3.0 and arrow is on version 5.0 — so I should be good to use this"