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
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.