freecad / developershandbook Goto Github PK

By default, bundle install behaves analogously to sudo pip install, which can cause system breakage. This can be avoided by adding the --path flag (deprecated) to indicate an installation path other than under /usr/local, or putting that setting into a configuration file via e.g. bundle config set path vendor/bundle.

Besides being sparse, the README gives instructions that are not quite necessary, for example instructing users to install Jekyll when that dependency can be taken care of by the subsequent bundle install step.

1. In this markdown:
   

   DevelopersHandbook/technical/translation.md

   Lines 109 to 115 in 245f3d3

   	### Python
   	In your Python code, import FreeCAD, then create a function called `translate` with the following code:
   	```python
   	translate = FreeCAD.Qt.translate
   	```

   
   I only see Qt translation by function, but it is possible to translate using tr method from QObject.
   In my opinion, this is a much better option (especially when object-oriented style is used).
   Actually lupdate do not care about parent class, so it should be even possible to implement a custom method:

   class MyGreatClassAlsoExpandingAnotherClassSoItHasALongName:
       def tr(self, text: str) -> str:
           return translate('MyGreatClassAlsoExpandingAnotherClassSoItHasALongName', text)
   	def runTr(self):
   		print(self.tr("My transalted text"))

   Should this translation pattern be encouraged? Or there are reasons why this is not mentioned here?
   (There are problems with subclassing, but I know a workaround for this.)

2. This is a very frustrating error:
   

   DevelopersHandbook/technical/translation.md

   Line 127 in 245f3d3

   print(translate("MyMod", f"This won't {work}")) # NO!

   
   It is so frustrating that I created a flake8 plugin to detect these errors. Can I advertise this flake8 plugin/pre-commit check here?

I'm not over-fond of the hashtag symbol, but I leave it to someone with more CSS and HTML talent than I to implement something nicer.

Originally posted by @chennes in #68 (comment)

Handbook as it now is bright white. It also isn't playing nice with the https://darkreader.org/ extension.

FreeCAD/FreeCAD#9339 (comment)

The favicon served on the deployed page https://freecad.github.io/DevelopersHandbook is actually coming from the FreeCAD-blog repo, untouched in almost 4.5 years, deployed at https://freecad.github.io. For resiliency (and silencing a warning during local development), this file should be included in this repo as well.

Generally, any time I start a new project I write an informal text file to "future me" just in case I need to reproduce "what the heck did I do to get here?"

Just in case these are useful for others, these are my notes for doing c++ dev on CLion, a JetBrains tool, on an Ubuntu variant (PopOS!).

2023-February
  PopOS! 22.04 LTS
  CLion CLion 2023.1
    Build #CL-231.8109.174, built on March 28, 2023
  Linux 6.1.11-76060111-generic

First, follow https://wiki.freecad.org/Compile_on_Linux

Specifically, do all the apt-get and tool installations. Make sure that includes `sudo apt-get install qtwebengine5-dev`

Don't worry about Python libraries yet, we will let CLion install those through venv(?)

> git clone https://github.com/FreeCAD/FreeCAD.git freecad-master

Or, use whatever target name you want. I personally recommend that you _don't_ call it `freecad`. You will probably
end up with multiple versions of FreeCad on your machine, including the official binary distribution called "freecad",
so giving this directory that plain name is probably a bad idea.

Then delete the `cmake-build-debug` sub-directory. Cmake should be building that directory frestly on it's own. I don't
know why that directory is in the repo. Having it pre-exist confuses the *#@$ out of CLion.

Start CLion, choose Open. Select the repo directory and click on Ok.

Then, from the main screen, look for the Configuration drop down. If it says "Add Configuration..." wait a few minutes
while CLion parses everything for the first time. Hopefully, it says "FreeCADMain | Debug" after a while. If it doesn't, you
might have to choose things directly from the drop down.

Then, go to the Build menu and select "Build All in 'Debug'". You MUST do this at least once before anything else will
really work.

Go get a cup of coffee while it does a first-pass compile and build. By default, it uses up all but two of your machine's
core threads. Expect all your computer fans to go on full speed. You can tweak this later. You will see quite a few
warning about stuff. Ignore those. Later incremental changes should be nice and fast, but this first build is gonna take a
while. With tweaking, I got mine down to 14 minutes.

You can help CLion with memory issues if you bump up the heap size. It defaults to 2048 MB. I moved mine up to
8096 MB. Chose "Help" then "Change Memory Settings".

It should mostly work now. Mostly. Simply click on the "run" icon to see it run.

If you start messing about with Python or use other workbenches, you will want set up Python properly. My instructions
here are muddy. You might have to externally install more Python stuff.

The answer lies in "File" then "Settings" then "Build, Execution, Deployment" then "Python Interpreter". Then click on
"Add Interpreter", then "Choose Interpreter", then "Virtual Environment" with 3.10, then "Ok" and then closed the
Settings. Then, in theory, some packages should install.

Start FreeCAD again. Open the Python Console. Does running `sys.version` give you the 3.10 you would expect?

This issue is to capture knowledge and notes as the topological naming problem fixes are transferred from the Real Thunder branch to the main one.

Markdown format is preferred for convenience in a future collation of this information, but not required.

We are preserving author credit by waiting to merge comments. Each author is welcome to keep editing their comment, or use multiple comments as they see fit.

I've discovered recently this developers handbook, by accident, and I have been quite surprised how much the "assembly" question is emphasized. Looking at the developers involved in this handbook, I can't fail to notice that NONE of the contributors has EVER talked and participated in the FreeCAD assembly forums. I also have NEVER EVER seen any assembly model made by any of these contributors (to this handbook).

So here is my issue: if assemblies are such an important feature for a 3D CAD software, how come none of you has tried to improve and otherwise to interact with existing assembly workbenches ? Before wanting to impose random grand visions on the rest of the FreeCAD community, I'd like to see proof that the people who write such things as :

Assembly is a core feature of modern CAD systems

do indeed know what assemblies are about, what are the specific problems and existing solutions.

Without an integrated assembly capability, users are forced to use one of several add-on options. With competing alternatives available, collaboration and interoperability is negatively affected

This is technical nonsense and only political propaganda. I know of course where this comes from, but before wanting to impose such obvious lies on the rest of us, I invite any wannabee contributor to be able to show complex assemblies that he had made using FreeCAD. Open-source is about "show me the code" so anyone pretending anything about assemblies will be invited to "show me your assembly" .

There are many FreeCAD users who have indeed done assemblies, of various sizes and complexities, and who have posted their achievements in the forum, but they don't seem to have contributed to this "roadmap". Why is this roadmap not done in the open ? Why is this not discussed in the Open Discussion forum ? What is the hidden agenda ?

This does not work out of the box with the supplied instructions. I had to install a lot of libraries manually

Bundler::GemNotFound: Could not find fast-stemmer-1.0.2.gem for installation

gem install fast-stemmer
gem install jekyll-sass-converter

And still I cannot get it to run

Installing yajl-ruby 1.1.0 with native extensions
Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

On Linux Mint 20.3, I could not locate pre-commit using Synaptic or command "apt install pre-commit".

I was able to install something called pre-commit using "pip install pre-commit" and install it in Source/FreeCAD with "pre-commit install".

Not sure if the instructions should be changed or if I've installed the wrong thing.

All markdown files have a frontmatter section with a title and description element. These elements are immediately used within the content of the markdown file with Jekyll specific shortcodes like {{page.title}} and {{page.description}}.

This is generally considered bad practice in writing markdown files.

• Markdown files should be correctly readable in its own -> the use of these shortcodes prevents this, as you can see if you open an *.md file with the GitHub editor or any other local text editor capable of previewing markdown
• Title and description are important parts of the text content of the file, as they are rendered on the webpage as such. These should not be set with frontmatter only. Frontmatter should be solely used to add additional meta information to the markdown file (like date, author, tags etc.)
• mixing of generator specific commands with markdown content prevents easy portability of the md file

possible solution:

• rewrite the markdown files

Highlighting how to add debug symbols to builds and then what tools that can be employed to leverage them

• Section on how to check coverity scans for FreeCAD
• Section on how to check pvs-studio scans for FreeCAD
• Section on how to trigger scans
• Implement automation for said scans (ATM @sasobadovinac is triggering them manually)

reference: FreeCAD/FreeCAD#11091 (comment)

Make it easy for devs familiar with docker to 'hit the ground running' with a dev docker image.

Add it to https://freecad.github.io/DevelopersHandbook/gettingstarted/

I can not install the ruby bundles without the missing Gemfile. With only the present Gemfile.lock, bundle install will return an error.
System macOS M1, freshly cloned repo with git clone https://github.com/FreeCAD/DevelopersHandbook.git freecad-DevelopersHandbook.

freecad-DevelopersHandbook git:(master) ✗ uname -m
arm64
➜  freecad-DevelopersHandbook git:(master) ✗ ruby -v
ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [arm64-darwin22]
➜  freecad-DevelopersHandbook git:(master) ✗ bundle -v
Bundler version 2.3.26
➜  freecad-DevelopersHandbook git:(master) ✗ bundle install
Could not locate Gemfile

See FreeCAD/FreeCAD-Homepage#135

Where should this live in the handbook?

I've annotated the above screenshot to show where i expected to find the classic markdown link icon so one could anchor their link to a specific section within the page.

Is there something in Jekyll to enable this feature ?

As part of the technical documentation it would be great to have a section explaining how the built executable gets packaged for various platforms and OSs.

Considering this image, there are several tools enabled that shouldn't be, but for different reasons.

It would be nice to create issues in the tracker and reference these problems while being able to say what's wrong without reinventing the wheel every time. For example, the issue creator should be able to say;
"The Draft 'manage layers' button is enabled when it shouldn't be per guideline XXX.YYY.Z"
or
"The link tool group is improperly enabled per guideline XXX.YYY.X"

Whichever number scheme is used should allow the handbook to be reorganized in the future. large pages may be split into smaller ones.

The stylebook should be revised with guidance about which workbenches are enabled in the selector by default.

Many workbenches are not usable without the user taking additional steps to install software.
All enabled workbenches should be usable from the default installation.

We need a page with an outline of the release process. this page can be essentially an outline with links to relevant pages for the key steps

We need an outline of how an interim release is done.

Hi there !

In order to reduce the potential for confusion, it would be sensible to adopt different terms for the documentation of the development side and the association side.
Although the use of the term "handbook" makes sense to a certain extent for both cases, a distinction is preferable.

A number of other closely related terms can be used :
For software development documentation, Google uses "Tech Dev Guide", WordPress uses "Developer Resources", Apple, Blender and KiCAD uses simply "Developer Documentation" but also "Handbook" for Blender, etc. We can look into many other examples...
Some FOSS projects like QGIS and Inkscape do not have a special name for that but direct links to theirs Getting Started, Code Style, Repos, Debugging, etc.

For the Association side of things, most FOSS associations/foundations like the Free Software Foundation, the Open Source Initiative, Blender do not have any special name or a special "space" to describe precisely how they operate, but display some general information's on their main website, generally in the About page. Some like Godot have a dedicated website but no special name.

If you feel this issue is better posted in the FPA repo, I'll gladly do so =P
Thank you !

Step-by-step process that is used to locate offending code when hunting for what commit a certain bug was introduced

• How to structure addons
  • Avoid name clashes w/ FC core or other addons (FredsFactory/FreeCAD_AirPlaneDesign#36 (comment))
  • Recommended linting practices
  • Recommended UI/UX practices
• How to create SVG icons (remove inkscape 'sodipop' metadata)
• How to create experimental branches and orient their testers to take advantage of the Addon Manager feature that allows installing said branches for testing in FC (jaheyns/CfdOF#76 (comment))
• How to try to limit 3rd party dependencies when available
• How to translate addons
  • How to add their translations to crowdin

What an excellent handbook!
I wish this repo had existed when I started FreeCAD modification.

By request in FreeCAD/FreeCAD#11505 (comment), I want to add some info about FreeCAD-stubs.

Although, the installation process is very simple, it may be worth it to mention that there are Python stubs, but not installed together with FreeCAD binaries.

Move the table of contents from the top of the page to the right column (which is currently empty). Keep table of contents static or hovering as page scrolls down or up. When user scrolls down/up page and crosses the threshold of different sections, include the ability for the TOC to bold the section header that user is scrolling through in the TOC.

A developer who is used to working with a modern IDE including breakpoints and watch variables is quickly frustrated working on the Python side of FreeCAD.

I've tried all the documented methods on the wiki and in many forum posts and never succeeded in getting a debugger to work with the FreeCAD internal python interpreter.

We should recommend a single environment per platform that we know works. Then if the developer wants to use something different, they at least have a reference platform for how things should behave.