Path Development Philosophy

Here's the place for discussion related to CAM/CNC and the development of the Path module.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
User avatar
sliptonic
Veteran
Posts: 3457
Joined: Tue Oct 25, 2011 10:46 pm
Location: Columbia, Missouri
Contact:

Path Development Philosophy

Post by sliptonic »

In a recent online meetup we had some discussion about how Path development should proceed. It was suggested that I write this up so it could get broader visibility and discussion. I'm recreating this from memory so please correct me if I get something wrong or miss something.

code quality

Overall we're striving for clean, testable, and efficient code with good separation of concerns. We want it easy for new developers to find relevant code and suggest improvements without the whole becoming unmaintainable.

set up for development
Fork FreeCAD on github and then clone your fork to your local machine. You can then add another remote reference to your local repo that points to the upstream. For me, this looks like this:
upstream -> FreeCAD/FreeCAD
origin -> Sliptonic/FreeCAD

Phased Development
This is a collaborative effort. So getting consensus about the overall direction is important but can be difficult. Therefore we suggest the following general process. The worst thing that can happen is to spend weeks or months developing a huge feature which is deemed incompatible with the current application or desired direction. Avoid this by communicating frequently and working incrementally.

1) Work out and describe your ideas publicly. Get some consensus about the direction
2) Develop in your own github branch. Push it publicly so other devs can review, test, and comment
3) Cleanup code and Create a Draft PR for more formal code review
4) Test. Test. Test.
4) Remove the draft status to request merge to master

Working out ideas.
Before you spend a lot of time developing your ideas, make sure they align with the general thinking and direction around Path. This is all about conversation. Create a new post in this Development Path section and update it as you go. Don't scatter the discussion all over the place. Pictures are great. Posts that are just pages of text are not. Hint: If you're not getting constructive (and critical) feedback, chances are nobody knows what you're talking about.
Take the time to work through the visual/UI part. You can use QT Designer to create or modify the .ui files and make screenshots of those.
Working out ideas isn't just about the feature but also the order of development to merge it. Enormous pull requests are difficult to rebase and very difficult to review. Break big ideas down into digestible steps!

Developing
As you start developing, you should periodically rebase your feature branch on upstream/master and push your branch to your github repo.
Rebasing and push/force here is better than merging master into your feature branch and will keep the history cleaner.

If your idea is an incremental change you can continue developing this way until it's finished.

If you're introducing an entirely new feature, you should set this up as an 'experimental feature' These features are hidden from users by default unless they have opted to use them.

If your idea has broad effect on existing functionality it will require considerable discussion. The goal will be to introduce features incrementally without breaking existing functionality whenever possible. If an improvement introduces a breaking change, it will require even more discussion and consensus. Ask for help!

We have a very useful module called PathLog for both debugging and logging to the console. I recommend you use this over print() statements for testing. You'll find examples of use throughout the path python code.

Create a Pull Request in Draft mode
From Github you can create a Draft pull request to pull from your feature branch into FreeCAD/Master. Whenever you update your own repo, the PR will be automatically updated. Draft PRs do not trigger the automated testing and will not be merged into master.

Cleanup your code
Continue developing until you're ready to merge. Before moving your PR out of draft status, rebase it again and do any final clean up and formatting.

We generally follow PEP8 for python formatting. In fact, I suggest you use Black to format your python before submitting it.

Remove dead code, commented out sections, and unnecessary debug lines.
Include a copyright header at the top.

Testing
Design and implement your code so that it is testable and write appropriate tests.
You can run the Path test suite (and only the Path tests) like this:

Code: Select all

./bin/FreeCADCmd -t TestPathApp
Remove the Draft status from the Pull Request
Additional code reviewers or changes may be suggested.
Celebrate when it's merged!

Resources.
If you want to improve your skills, I find the following resources to be very good.
Writing Idiomatic Python
Dave Farley's YouTube channel is a great resource about software development philosophy.
troyp76
Posts: 32
Joined: Thu May 06, 2021 8:05 am

Re: Path Development Philosophy

Post by troyp76 »

sliptonic wrote: Tue Oct 19, 2021 7:11 pm In a recent online meetup we had some discussion about how Path development should proceed. It was suggested that I write this up so it could get broader visibility and discussion. I'm recreating this from memory so please correct me if I get something wrong or miss something.
Thanks for this post. It captures what was discussed plus more.
MrZando
Posts: 3
Joined: Tue Sep 21, 2021 3:59 pm

Re: Path Development Philosophy

Post by MrZando »

Sliptonic, Thanks for the summery (and all your work). Wish I could have listened in but life had other plans :)
MRx
Posts: 319
Joined: Wed Jul 08, 2020 5:59 am
Location: Tainan / Taiwan

Re: Path Development Philosophy

Post by MRx »

How about the recomputation part in the Path modules, currently I consider this as absolutely broken

- add a new tool to the tool list -- it will force a complete recomputation of all existing paths
- remove a path operation -- it will force a complete recomputation of all existing paths
- click on adaptive -- first thing it will do is generating a toolpath with default settings which is not good either, it should only be created once a user has clicked on apply, eg. why should a path by default mill around a hole (it's just a detail but I'd rather select outline before it eats CPU time and creates a by default nonsense path)
- disable / enable a path operation -- it will recompute the corresponding paths

Any feedback on that?
openBrain
Veteran
Posts: 9034
Joined: Fri Nov 09, 2018 5:38 pm
Contact:

Re: Path Development Philosophy

Post by openBrain »

I would add that during PR review process (especially PRs with several commits) one should make extensive use of 'git commit --fixup SHA' and 'git rebase --interactive --autos quash SHA^' so fixes are squashed appropriately. Nothing more horrible than a list of initial commits followed by a list of fix commits. Squashing everything together is hardly better. :)
openBrain
Veteran
Posts: 9034
Joined: Fri Nov 09, 2018 5:38 pm
Contact:

Re: Path Development Philosophy

Post by openBrain »

MRx wrote: Tue Nov 23, 2021 5:52 am Any feedback on that?
Yes, please do not hijack. Thread is about setting rules and guidelines for Path development, not discussing what should be actually developed.
User avatar
sliptonic
Veteran
Posts: 3457
Joined: Tue Oct 25, 2011 10:46 pm
Location: Columbia, Missouri
Contact:

Re: Path Development Philosophy

Post by sliptonic »

openBrain wrote: Tue Nov 23, 2021 7:29 am I would add that during PR review process (especially PRs with several commits) one should make extensive use of 'git commit --fixup SHA' and 'git rebase --interactive --autos quash SHA^' so fixes are squashed appropriately. Nothing more horrible than a list of initial commits followed by a list of fix commits. Squashing everything together is hardly better. :)
Good stuff. a quick description of what each of those commands does would be helpful. In fact, Someone could do an entire tutorial or wiki page on good git practice. I know it's covered very well elsewhere on the web but we get a lot of first-time contributors here because of the post-processers.
User avatar
sliptonic
Veteran
Posts: 3457
Joined: Tue Oct 25, 2011 10:46 pm
Location: Columbia, Missouri
Contact:

Re: Path Development Philosophy

Post by sliptonic »

openBrain wrote: Tue Nov 23, 2021 7:31 am
MRx wrote: Tue Nov 23, 2021 5:52 am Any feedback on that?
Yes, please do not hijack. Thread is about setting rules and guidelines for Path development, not discussing what should be actually developed.
I agree with openBrain. Please open a dedicated topic. I'm traveling with family so only on here intermittently.
MRx
Posts: 319
Joined: Wed Jul 08, 2020 5:59 am
Location: Tainan / Taiwan

Re: Path Development Philosophy

Post by MRx »

No problem. I'll open another discussion about that.
User avatar
onekk
Veteran
Posts: 6144
Joined: Sat Jan 17, 2015 7:48 am
Contact:

Re: Path Development Philosophy

Post by onekk »

I agree with the philosophy.

What i find difficult is to manage sources in the way they are actually written.

It is difficult to follow "without a scheme" the path of the Path working.

Maybe some basic explication, will help beginners to be more aware of the "internal work" of PathScripts.

I have not guessed what a model is when creating jobs, so I'm assigning to the "model " a simple cube 1x1x1mm and code the rest without problems.

But obviously I'm doing something wrong.

Regards

Carlo D.
GitHub page: https://github.com/onekk/freecad-doc.
- In deep articles on FreeCAD.
- Learning how to model with scripting.
- Various other stuffs.

Blog: https://okkmkblog.wordpress.com/
Post Reply