RoadMap:: Objectives

[dcowden]

Roadmap step 2: consensus on objectives for our next huge CQ version.

Proposed objectives are here: https://github.com/CadQuery/cadquery/wiki/RoadMap#objectives

[jmwright]

In CQ 3.0

The bump of the major version number is usually for breaking changes in the API. Is that warranted here?

Improved documentation

Have ideas been promoted to achieve this? We do have a sampling of requests on improving the docs in the issue tracker, but I wouldn't know where to focus to have the most impact right now. We have had multiple users say that they want more examples, especially ones that help new users go from beginner to intermediate. That leads to the next item.

More examples

The feedback I've seen is that the complexity of our examples ramps up too quickly. If someone had the time to write a guide similar to the Rust language's that takes a developer through the whole journey from knowing nothing to being somewhere above intermediate, that would be great. We have a very light (and truncated) version of this in the docs already, but I think it would really help users to have an in-depth guide that walks them through the whole journey.

I also think users need docs on things like using extensions (cq_warehouse, cq-kit, etc), and I don't think we even mention that in the docs now.

first-class extensions

We still also need to define where the line is between core and extensions. How can I objectively evaluate when to tell a contributor that their change needs to be in an extension rather than core? I'd prefer to have some rule of thumb or standard to refer to, and not just have it be my opinion.

5. Add a modeling context, which can be used to support back-references, tagging, and queries when using the direct api

I don't have a strong opinion on this, but I've seen some comments (including from Dave) that seem to suggest that the current context system in CQ is/was a poor design. While there is certainly room for improvement to get the new functionality that has been discussed, the current context system has served us well since for about a decade and the lessons learned from it should be incorporated into any new system. We need to avoid assuming that the old context system has nothing to inform the new design.

[dcowden]

@jmwright
thank you. replying below, integrating clarifications for these in the roadmap doc.

In CQ 3.0

The bump of the major version number is usually for breaking changes in the API. Is that warranted here?

the proposed roadmap ends with removal of deprecated methods, which would be a breaking change. I assumed that we would not have other breaking changes to do, so i chose 3.0. Choosing 3.0 was meant to re-affirm that the majority of this work will be done without breaking existing scripts-- and thus can stay on the 2.x series.

Improved documentation

Have ideas been promoted to achieve this? We do have a sampling of requests on improving the docs in the issue tracker, but I wouldn't know where to focus to have the most impact right now. We have had multiple users say that they want more examples, especially ones that help new users go from beginner to intermediate. That leads to the next item.

More examples

The feedback I've seen is that the complexity of our examples ramps up too quickly. If someone had the time to write a guide similar to the Rust language's that takes a developer through the whole journey from knowing nothing to being somewhere above intermediate, that would be great. We have a very light (and truncated) version of this in the docs already, but I think it would really help users to have an in-depth guide that walks them through the whole journey.

More examples has been common, and I think you are right about the progression. There have been comments about the difficultly of learning both a fluent api and the underlying principles at the same time: i believe we are addressing that by having another api that's not fluent but does mostly the same thing.

Another thing that's been talked about is the different behavior of functions like circle that can be used in multiple contexts ( workplane and sketch) but dont do the same in those cases.

Another example is documentation on plugins, and how they integrate with the rest

I also think users need docs on things like using extensions (cq_warehouse, cq-kit, etc), and I don't think we even mention that in the docs now.

Yes using stevedore i hope to list supported extensions, and produce omnibus documentation that includes the combined capabilities of core + plugins. more here

first-class extensions

We still also need to define where the line is between core and extensions. How can I objectively evaluate when to tell a contributor that their change needs to be in an extension rather than core? I'd prefer to have some rule of thumb or standard to refer to, and not just have it be my opinion.

I agree. I hope to add seams that make these extension points clear. I hope to handle the difference between core and extensions the way django does-- basically extensions really never become core. Eventually they can be so common that the code/package becomes hosted by django, but the code stays package as it was. that's because moving into core breaks all the code out there for it when it was separate.

5. Add a modeling context, which can be used to support back-references, tagging, and queries when using the direct api

I don't have a strong opinion on this, but I've seen some comments (including from Dave) that seem to suggest that the current context system in CQ is/was a poor design. While there is certainly room for improvement to get the new functionality that has been discussed, the current context system has served us well since for about a decade and the lessons learned from it should be incorporated into any new system. We need to avoid assuming that the old context system has nothing to inform the new design.

Good point. specific example, CQContext implements a stack, which must be available for the fluent api, and wont be provided by a context tree.

[qwelyt]

Address usability concerns

Which are?
The most annoying for me as a novice is the propagation of error messages from occ/ocp up to the user. StdFail_NotDone BRep_API: Command not done tells me nothing. After a lot of fighting I now know that it is probably a fillet gone wrong. But the error messages really need to tell me something useful.

[dcowden]

@qwelyt thanks for raising this, I'd forgotten about it, but its a good thing to standardize. I'm not sure the right way, but i'll put the topic into the roadmap as an unresolved decision

[dcowden]

Hearing no more comments, I'm closing this discussion