Roadmap:: Rules of Engagement/Philosophy

[dcowden]

1. Rules of Engagement/Philosophy

The first step of roadmap discussions is to set the rules for roadmap discussions!

The proposed rules of engagement are at https://github.com/CadQuery/cadquery/wiki/RoadMap#rules-of-engagementphilosophy.

The goal of this discussion is to reach consensus on these rules, before moving on to our objectives

[qwelyt]

First three points seems fine (maybe number them so discussion becomes easier). About tests though; should PRs be rejected if they don't have "lots of tests"? I think every PR should have a least one test to show what it solves, but what is "lots"? I'm open for flexibility.

Favor progress over correctness when both are not possible

Can you clarify what you mean by this?

As a volunteer project, but we want to keep moving forward. We should always abide non-action, but we NOT abide blocking progress through in-action

And also this.

[dcowden]

Ok, I numbered them best i could-- evidently you cant sub-number in markdown?

Clarifications:

Favor progress over correctness when both are not possible

We have had several cases where a contributor did quite a lot of valuable work, and seeking to merge. The discussion ended up in an argument over a couple of tiny syntax details that were a matter of style, and then eventually nothing was done. That's the kind of situation we should avoid.

As a volunteer project, but we want to keep moving forward. We should always abide non-action, but we NOT abide blocking progress through in-action

If you're active in the project, and you discuss/disagree, then the community should strive reach consensus. But if someone doesn't agree, but then either (a) disappears, or (b) simply refuses to discuss, (non-action), then we need to move forward.

[qwelyt]

Is this wiki supposed to keep living on after the discussions so it can be pointed to? If so I suggest that examples like these are added.

Suggested refactor:

1. User experience is first.

   • Most users are not python experts. Keep things simple when possible.
   • Consistency in the codebase is important. We don't want some methods having parameters in snake_case and others in camelCase. Nor do we want parameters with the same name take a letter in some methods, words in another, and enums in a third. They should all be consistent.

2. Contributing should be easy

   • volunteers don't have time to read thousands of likes of code. Make things small and self contained as much as possible.
   • Tests help to document what the code does. Write tests to showcase how methods work and whats supposed to not work. Each pull request should have tests to show what has changed or been added (exception is documentation changed).

3. Keep it as it is

4. Favour progress over correctness when both are not possible.

   • If everything looks fine except some parts of the syntax, then accept that things look odd. Fix it either in the same PR or in a later PR. Do not block the volunteers work.

5. This is a volunteer project. Everyone who contributed commit their free time to it. We want to move forward and keep the community engaged.

   • We strive for consensus when disagreement occurs. However, core developers will have the final say if consensus can not be reached.
   • If a participant disappears or refuses to continue the discussion the discussion becomes stake and core developers will take action based on the discussion. We want to move forward.

[dcowden]

Is this wiki supposed to keep living on after the discussions so it can be pointed to? If so I suggest that examples like these are added

Yes that's the plan. Good idea to add the examples. thanks for the suggestions, i'll integrate these

[gumyr]

With respect to the modelling context, I would expect that it either stores enough information to regenerate the model at any state or stores the model at all states (classic trade-off between time and space). With such a context, one would be able to introduce new operations like "find the edges produced by operation x". What would the scope of such a context be: a Solid, a Compound, an Assembly? Would models/contexts be able to be combined - say create model one which would have its own context; then create model two with a separate context; then combine the two models - how many context are there now? 2 or 3?

[dcowden]

With such a context, one would be able to introduce new operations like "find the edges produced by operation x".

Definitely what i'm after. and also possibly 'find all of the edges before/after this operation'

What would the scope of such a context be: a Solid, a Compound, an Assembly? Would models/contexts be able to be combined - say create model one which would have its own context; then create model two with a separate context; then combine the two models - how many context are there now? 2 or 3?

Very good question. I struggled with this when intially creqting CQContext ( the notion of the 'context' solid). But lets move this conversation into this discussion topic. I went ahead and cross posted your note above there

[gumyr]

With respect to PEP8/PEP484 and snake_case method names, it would be easy enough to add snake_case aliases to all of the existing camelCase names. At some future date the camelCase names could be removed.

[Jojain]

PyQt or PySide (I don't remember which one, or maybe the two) are already doing this which indeed can be added programmatically so indeed it's not super complicated. If we add new API following the PEPs then it would be mandatory to add the aliases otherwise we would just increase incoherence across the API (which we are trying to solve)

[dcowden]

+1 i like this idea. provides a good path forward and lets us deprecate my old mess.

[dcowden]

@Jojain @gumyr added this thought into the roadmap. I converted roadmap steps in the wiki page to text, so i could add this detail, and that way we can edit more details later.

[qwelyt]

This should probably be discussed in #1109

[dcowden]

Ok, for clarity, I believe i've incorporated the suggestions so far in the wiki page

[michaelgale]

@dcowden I really love what you're doing here in terms of scoping out a roadmap for the future. I've been a CQ user since around 2017, and its an invaluable tool. So far, I am in agreement with principles and goals outlined and I'm glad that there is a sensitivity to not make breaking changes--at least not right away! In particular the PEP8 method naming which is potentially a breaking change without aliasing.

I'm not sure I can contribute anything meaningful other moral support but I shall look forward to following this story as it unfolds.

[dcowden]

thanks @michaelgale for the words of encouragement!

I'm very excited about several new features we have been talking a lot about:

1. Selectors based on what operation created or modified geometry
2. snapping, IE, sketching assisted by tangent, mid, end, or start points
3. a new api that's NOT fluent, so that its easier for users to understand whats going on when they use the fluent api, and to downshift when they need it

[michaelgale]

1. Selectors based on what operation created or modified geometry

Selectors have to be CQ's "magic sauce" -- they are soooooo useful!

[dcowden]

1. Selectors based on what operation created or modified geometry

Selectors have to be CQ's "magic sauce" -- they are soooooo useful!

Thanks. Unsurprisingly, they were the absolutely hardest part of the early CQ work. i remember spending a full notebook of scribblings thinking about the problem 'how do you build things when you cant click the screen!'

Selectors are now [no longer] unique to CQ. Onshape uses them, and their implementation is actually more sophisticated than CQs. But CQ came first. ;)

[jdegenstein]

I understand that this is not the first priority, but I wanted to comment on the release schedule. It has been a long time since the last release and there are a lot of new features that are important and powerful in the current main (such as the combine argument in the eachpoint method). I believe not having more frequent releases is making it harder for new users and limits the growth of the CQ userbase. I believe that this point is support by ROE 5 -- to keep things moving forward.

Regarding consistency in the codebase, I agree with prior proposals about moving entirely to snake_case and keeping linked copies of methods to avoid breaking changes until a later release. I also feel strongly that the input data types should be made consistent, and this is a particular problem for moving/translation methods (tuple, cq.Vector, cq.Location(cq.Vector()), etc).

[dcowden]

@jdegenstein thank you for these comments!

Regarding release schedules, I will add a discussion topic. I know there is broad agreement that the release schedule is not what people want, but there is also broad disagreement about what strategy will work best. I created this discussion because you're right, we need to work it out.

Regarding consistency in the codebase, i have heard the vector location/tuple complaint often. I'll add that to the roadmap. i'm not sure if everyone will agree, but at least that way we'll discuss!

[adam-urbanczyk]

What is the complaint about tuple/vector/location?

[dcowden]

@adam-urbanczyk the complaint is that we inconsistently use one or the others in various places, and sometimes accept either but not in others.

[adam-urbanczyk]

Could you be more specific than that? Location and vector/tuple have very different semantics so obviously some methods won't be accepting all of them.

[gumyr]

Many methods accept VectorLike but some require a Vector (I think this is mostly the Direct API ones).

[jmwright]

I'll scope my comments to only the section referenced in the title.

Most users are not python experts.

Can we say this with any certainty? We've never done a survey of our community.

Consistency in the codebase is important.

Agreed, and not just in consistency of how snake_case vs camelCase is used, but logically consistent as well so that if a user learns a concept that applies to one operation, they can expect that it would apply to a different, similar operation as well. There have been discussions about how CadQuery acts differently in some places that should act the same.

Volunteers don't have time to understand thousands of lines of code. Make things small and self contained as much as possible.

This is very broad and open to interpretation. What is the success condition of this? What does "small and self contained" mean? Doesn't this have to scale to the situation as well? I think that if you are wanting to contribute code that fundamentally effects how CQ operates, it's reasonable for the core devs to expect that you have familiarized yourself with all the related code, even if there is quite a bit of it. The inverse of that is that it's not reasonable (in most cases) to expect someone contributing documentation updates to understand the underlying code.

5. As a volunteer project, but we want to keep moving forward.

Is this supposed to be nested under item 4? Also, is it supposed to read something like "As a volunteer project we understand people have limited time, but we want to keep moving forward."

[dcowden]

@jmwright thanks for the comments!

Can we say this with any certainty? We've never done a survey of our community.

I have been monitoring the questions and there are certainly lots of people who are not python experts. I just dont know what percent to total they are. I can downgrade to 'many', which i'm comfortable is true. But also, i think even if most users ARE python experts, it probably supports the argument that we need to be friendlier to use ( because it means the ones that are not python experts can't figure it out.

Agreed, and not just in consistency of how snake_case vs camelCase is used, but logically consistent as well so that if a user learns a concept that applies to one operation, they can expect that it would apply to a different, similar operation as well. There have been discussions about how CadQuery acts differently in some places that should act the same.

Very good point. I agree completely, on example has been confusion on wire 2d vs face 2d. I'll add a reflection of this comment into the writeup.

This is very broad and open to interpretation. What is the success condition of this? What does "small and self contained" mean? Doesn't this have to scale to the situation as well? I think that if you are wanting to contribute code that fundamentally effects how CQ operates, it's reasonable for the core devs to expect that you have familiarized yourself with all the related code, even if there is quite a bit of it. The inverse of that is that it's not reasonable (in most cases) to expect someone contributing documentation updates to understand the underlying code.

right now you have to understand a lot in order to change a little. A more modular design would provide better comfort that you can change one thing, after learning less, and have less blast radius. On example would be CAD operations. Right now, the bulk of the code is mixed into cq.py and shape.py, which means changes affect everywhere. If we had operations separated into classes, you could comfortably change just cut, with unit tests around only that component, and you'd only need to understand that.

Right now, i feel like to make a change, frequently you need to understand OCCT/OCP, and the shape layer, and the fluent layer. The tests re-enforce this by being basically all high level integration tests, all in one file.

In terms of success condition, i'm seeking only 'more modular than now'

Is this supposed to be nested under item 4? Also, is it supposed to read something like "As a volunteer project we understand people have limited time, but we want to keep moving forward."
That was a left-over from grouping things under the other one, so i just deleted it

[dcowden]

With no more comments, I think we have documented consensus