Upcoming directory restructuring
Hi all,
At the hackfest we discussed a revised directory structure to better organize our code, This is a heads up that we plan on doing this reorganization in a couple of week (to give time for existing patches, etc. to land).
The purpose of the reorganization is to make it more obvious where to find different pieces of code. At the moment our code tends to be distributed over lots of different directories (especially the code that manipulates SVG and the code for our 100+(!) GUI elements).
The proposed directory structure can be found at:
http://wiki.inkscape.org/wiki/index.php/Source_Directory_Structure
You can comment on the proposed change here or on the wiki page.
We also discussed a requirement that all files should have at least one or two sentences to document what their contents does. This should really help new developers (and prevent code duplication).
Tav
good proposal overall!
I'd make some changes & remarks though (I think there are a bit too many folders):
2geom -> libraries/2geom extension -> extensions io -> extensions/io manipulation/knots -> ui/knot-manipulation manipulation/misc -> manipulation/ manipulation/chemistry -> manipulation/ manipulation/selection -> manipulation/ packaging -> ../packaging (same as now)
- What's the point of display/control ? - *nothing* UI-related out of ui/ - *nothing* non-needing-absolutely-UI in ui/ (so ui/widget/actions -> manipulation/actions (or "verbs", but I'd prefer "actions" )) ( the goal will eventually be to put in the root cmakelists a "if(WITH_UI)include_directories(ui)endif()" ) - do we need ui/menu/ while we should have a generic menu generator from share/ui/menus/*.xml ? Same for toolbars & dialogs, if we have GActions and xml or glade files, we should not have much code to put in those folders (?) (Or maybe we can start with that and silmplify once there is less code)
On 03/28/2018 01:31 PM, Tavmjong Bah wrote:
The purpose of the reorganization is to make it more obvious where to find different pieces of code. At the moment our code tends to be distributed over lots of different directories (especially the code that manipulates SVG and the code for our 100+(!) GUI elements).
Sounds great! For the most part Git does okay with renames... so I'm not sure there's a huge amount of benefit in waiting. But if there's specific cases you know of, that's fine.
The proposed directory structure can be found at:
http://wiki.inkscape.org/wiki/index.php/Source_Directory_StructureYou can comment on the proposed change here or on the wiki page.
Looks good, curious about the logic behind moving packaging into src ?
We also discussed a requirement that all files should have at least one or two sentences to document what their contents does. This should really help new developers (and prevent code duplication).
I think that's a good idea, but please make sure it is a test that fails. Relying on humans to police it will cause it to decay quickly.
Ted
Hey,
I have heard that this is a big issue with Inkscape development, and this is one of those that prevents new coders from helping out. If the issue is more than just the directory, I believe there should be changes in the source code to make it easier for developers. How feasible is fixing the source code?
ML
From: Tavmjong Bahmailto:tavmjong@...8... Sent: Wednesday, March 28, 2018 2:51 PM To: inkscape-develmailto:inkscape-devel@...6... Subject: [Inkscape-devel] Upcoming directory restructuring
Hi all,
At the hackfest we discussed a revised directory structure to better organize our code, This is a heads up that we plan on doing this reorganization in a couple of week (to give time for existing patches, etc. to land).
The purpose of the reorganization is to make it more obvious where to find different pieces of code. At the moment our code tends to be distributed over lots of different directories (especially the code that manipulates SVG and the code for our 100+(!) GUI elements).
The proposed directory structure can be found at:
http://wiki.inkscape.org/wiki/index.php/Source_Directory_Structure
You can comment on the proposed change here or on the wiki page.
We also discussed a requirement that all files should have at least one or two sentences to document what their contents does. This should really help new developers (and prevent code duplication).
Tav
------------------------------------------------------------------------------ Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
On Wed, Mar 28, 2018 at 02:32:12PM -0500, Ted Gould wrote:
On 03/28/2018 01:31 PM, Tavmjong Bah wrote:
The purpose of the reorganization is to make it more obvious where to find different pieces of code. At the moment our code tends to be distributed over lots of different directories (especially the code that manipulates SVG and the code for our 100+(!) GUI elements).
Sounds great! For the most part Git does okay with renames... so I'm not sure there's a huge amount of benefit in waiting. But if there's specific cases you know of, that's fine.
The proposed directory structure can be found at:
http://wiki.inkscape.org/wiki/index.php/Source_Directory_StructureYou can comment on the proposed change here or on the wiki page.
Looks good, curious about the logic behind moving packaging into src ?
No, that's not going to happen. We caught that in review but guess that didn't get updated in wiki. The packaging dir will remain where it is.
We also discussed a requirement that all files should have at least one or two sentences to document what their contents does. This should really help new developers (and prevent code duplication).
I think that's a good idea, but please make sure it is a test that fails. Relying on humans to police it will cause it to decay quickly.
We were talking about doing these docs as doxygen @file tags, so they could be mechanically processed. I don't know if we'd do them as CI style landing requirements, but at the least we figure we'll try to do a pass collectively here Friday as part of the hackfest and add docs to as much as we can.
Bryce
Thanks Tavmjong,
I'm constantly struggling with the UI layout myself, so I really support this idea.
Especially "src/ui/widget" vs. "src/widgets" is really confusing.
Am 28.03.2018 um 21:28 schrieb Marc Jeanmougin:
io -> extensions/io
The files in src/io are not exclusively used by extensions (notably resource.h/cpp and probably others, too), so I'm not sure putting them into src/extension(s) would be a great idea. If extension-specific IO operations that are unlikely to be useful for the rest of the inkscape codebase could be moved to the extensions folder, that obviously makes sense, though.
packaging -> ../packaging (same as now)
I found that one, too. If it actually refers to the packaging folder in the root directory I also think it should stay there.
Another thing that might be good is if we could clarify the purpose of the "/util" folder, as both the current "util" and "helper" folders seem to be a collection of many different things. I added a code file myself already (helper/gettext) and I'm unsure even today if I put it into the right folder or what a more suitable location might have been.
One thing that might need a bit of attention could also be src/libnrtype, as it seems tightly integrated with Inkscape itself, specifically the cairo-renderer, so I'm not sure it can really be considered a library at this point.
Regards, Eduard
On Wed, Mar 28, 2018 at 07:33:59PM +0000, Miguel Lopez wrote:
Hey,
I have heard that this is a big issue with Inkscape development, and this is one of those that prevents new coders from helping out. If the issue is more than just the directory, I believe there should be changes in the source code to make it easier for developers. How feasible is fixing the source code?
ML
Hi Miguel, could you elaborate on this issue and how it affects new users?
Thanks, Bryce
From: Tavmjong Bahmailto:tavmjong@...8... Sent: Wednesday, March 28, 2018 2:51 PM To: inkscape-develmailto:inkscape-devel@...6... Subject: [Inkscape-devel] Upcoming directory restructuring
Hi all,
At the hackfest we discussed a revised directory structure to better organize our code, This is a heads up that we plan on doing this reorganization in a couple of week (to give time for existing patches, etc. to land).
The purpose of the reorganization is to make it more obvious where to find different pieces of code. At the moment our code tends to be distributed over lots of different directories (especially the code that manipulates SVG and the code for our 100+(!) GUI elements).
The proposed directory structure can be found at:
http://wiki.inkscape.org/wiki/index.php/Source_Directory_StructureYou can comment on the proposed change here or on the wiki page.
We also discussed a requirement that all files should have at least one or two sentences to document what their contents does. This should really help new developers (and prevent code duplication).
Tav
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot
Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
On Wed, 2018-03-28 at 21:28 +0200, Marc Jeanmougin wrote:
inkscape ├── packaging/* ├── po/* ├── share/* └── src ├── extensions │ ├── dbus │ ├── internal │ ├── io
src/io is a collection of core utilities that is used by the entire code-base for doing directory, settings, file, http and a few other tasks relating to opening file streams, looking for files in known places and looking after the differences between platforms.
It's not got anything to do with extensions (except for pointing to where extensions can be found)
Best Regards, Martin Owens
It has been a year or two since I touched the Inkscape codebase but have recently been introduced to the idea of a "Screaming architecture by Robert C. Martin/Uncle Bob" [1, 2] in other development efforts and started to practice it. It might not be doable right now for Inkscape but goes along the idea that we want WITH_UI flag in the build system (be able to build headless inkscape that is). Also it should make it easier for new developers to understand the codebase just by looking at the file/directory structure.
### Inside "src" folder There is nothing in the directory structure that clearly shows that this is an awesome SVG application.
1. What is the difference between "display" and "ui"? 2. Is "ui" a gui or also command line? 3. "Manipulation", it is impossible to understand what it is being manipulated with just a one-layer folder structure. 4. "Object", it is impossible to understand what an "object" is in this application without reading the code. 5. "extensions", what is the difference between a functionality implemented as an extension and right away in the core of the application? In my opinion the word "extension" is to vague. 6. "libraries" folder, 3rd party libraries included as source code, this is good idea but shouldn't 3rd party lib folder be next to "src" not inside it?
I did a quick example on the Inkscape wiki [3]. This is just an idea and I'm not sure how feasible it is for Inkscape as I don't understand the codebase that good. The main idea is that business logic, that is SVG functionality goes into "core". The core parts knows nothing about the entrypoints (gui, command line, http API) nor data providers (file system, in-memory data storage).
[1] https://8thlight.com/blog/uncle-bob/2011/09/30/Screaming-Architecture.html [2] https://www.slideshare.net/mattiabattiston/real-life-clean-architecture-6124... - One example on how "screaming architecture" could be implemented. [3] http://wiki.inkscape.org/wiki/index.php/Source_Directory_Structure_Screaming...
2018-03-29 3:41 GMT+02:00 Martin Owens <doctormo@...400...>:
On Wed, 2018-03-28 at 21:28 +0200, Marc Jeanmougin wrote:
inkscape ├── packaging/* ├── po/* ├── share/* └── src ├── extensions │ ├── dbus │ ├── internal │ ├── io
src/io is a collection of core utilities that is used by the entire code-base for doing directory, settings, file, http and a few other tasks relating to opening file streams, looking for files in known places and looking after the differences between platforms.
It's not got anything to do with extensions (except for pointing to where extensions can be found)
Best Regards, Martin Owens
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Hi Christoffer,
Thanks for your input!
On Thu, 2018-03-29 at 12:14 +0200, Christoffer Holmstedt wrote:
It has been a year or two since I touched the Inkscape codebase but have recently been introduced to the idea of a "Screaming architecture by Robert C. Martin/Uncle Bob" [1, 2] in other development efforts and started to practice it. It might not be doable right now for Inkscape but goes along the idea that we want WITH_UI flag in the build system (be able to build headless inkscape that is). Also it should make it easier for new developers to understand the codebase just by looking at the file/directory structure.
Interesting ideas, which I mostly agree with. The problem, I think, is that truly descriptive names are going to be too long.
### Inside "src" folder There is nothing in the directory structure that clearly shows that this is an awesome SVG application.
- What is the difference between "display" and "ui"?
display is for drawing the SVG and controls on the canvas. Perhaps is should be renamed to 'render' or 'canvas'.
- Is "ui" a gui or also command line?
Both.
- "Manipulation", it is impossible to understand what it is being
manipulated with just a one-layer folder structure.
True. Each folder will have a README to explain what is in the folder. I can't think of a better name.
- "Object", it is impossible to understand what an "object" is in
this application without reading the code.
This is the name we've always used. I can't think of a better one. It's explained in the README.
- "extensions", what is the difference between a functionality
implemented as an extension and right away in the core of the application? In my opinion the word "extension" is to vague.
I agree with this. Will bring it up for discussion today.
- "libraries" folder,
3rd party libraries included as source code, this is good idea but shouldn't 3rd party lib folder be next to "src" not inside it?
I'll bring this up for discussion.
I did a quick example on the Inkscape wiki [3]. This is just an idea and I'm not sure how feasible it is for Inkscape as I don't understand the codebase that good. The main idea is that business logic, that is SVG functionality goes into "core". The core parts knows nothing about the entrypoints (gui, command line, http API) nor data providers (file system, in-memory data storage).
[1] https://8thlight.com/blog/uncle-bob/2011/09/30/Screaming-Architec ture.html [2] https://www.slideshare.net/mattiabattiston/real-life-clean-archit ecture-61242830 - One example on how "screaming architecture" could be implemented. [3] http://wiki.inkscape.org/wiki/index.php/Source_Directory_Structur e_Screaming_Architecture
On Thu, 2018-03-29 at 00:13 +0200, Eduard Braun wrote:
One thing that might need a bit of attention could also be src/libnrtype, as it seems tightly integrated with Inkscape itself, specifically the cairo-renderer, so I'm not sure it can really be considered a library at this point.
Definitely not a library... The files contain code that really belongs in a lot of different places but splitting it up would be painful. And is handy to have all the font/text stuff in one place.
On Wed, 2018-03-28 at 21:28 +0200, Marc Jeanmougin wrote:
good proposal overall!
I'd make some changes & remarks though (I think there are a bit too many folders):
2geom -> libraries/2geom
We plan on moving this out of Inkscape.
extension -> extensions
This is the current name. 'extensions' might be better but...
io -> extensions/io
See doctormo's reply.
manipulation/knots -> ui/knot-manipulation
Will have to look at what is actually inside.
manipulation/misc -> manipulation/ manipulation/chemistry -> manipulation/ manipulation/selection -> manipulation/
Could evolve to this once things are cleaned up.
packaging -> ../packaging (same as now)
Everyone agrees, mistake on my part.
- What's the point of display/control ?
There are quite a few files for drawing controls (nodes, control lines) that have nothing to do with rendering SVG.
- *nothing* UI-related out of ui/
That is the goal... but may take a few iterations especially with text.
- *nothing* non-needing-absolutely-UI in ui/ (so ui/widget/actions ->
manipulation/actions (or "verbs", but I'd prefer "actions" )) ( the goal will eventually be to put in the root cmakelists a "if(WITH_UI)include_directories(ui)endif()" )
- do we need ui/menu/ while we should have a generic menu generator
from share/ui/menus/*.xml ? Same for toolbars & dialogs, if we have GActions and xml or glade files, we should not have much code to put in those folders (?) (Or maybe we can start with that and silmplify once there is less code)
We plan on migrating verbs to GActions but it will take some time. Alex has a three step plan. He's well on the way to finishing the first step. But it will take awhile.
2018-03-29 13:35 GMT+02:00 Tavmjong Bah <tavmjong@...8...>:
Hi Christoffer,
Thanks for your input!
On Thu, 2018-03-29 at 12:14 +0200, Christoffer Holmstedt wrote:
It has been a year or two since I touched the Inkscape codebase but have recently been introduced to the idea of a "Screaming architecture by Robert C. Martin/Uncle Bob" [1, 2] in other development efforts and started to practice it. It might not be doable right now for Inkscape but goes along the idea that we want WITH_UI flag in the build system (be able to build headless inkscape that is). Also it should make it easier for new developers to understand the codebase just by looking at the file/directory structure.
Interesting ideas, which I mostly agree with. The problem, I think, is that truly descriptive names are going to be too long.
Yea, that is for sure my experience as well. It is a trade off between longer more descriptive names or putting the information in documentation somehow.
### Inside "src" folder There is nothing in the directory structure that clearly shows that this is an awesome SVG application.
- What is the difference between "display" and "ui"?
display is for drawing the SVG and controls on the canvas. Perhaps is should be renamed to 'render' or 'canvas'.
'render' seems good if it includes both the SVG and the controls. 'canvas'
implies only the SVG parts for me. In the end maybe that is what we want separated "render::canvas" and "render::controls"
- Is "ui" a gui or also command line?
Both.
For me it sounds like those should probably be separated "ui::gtkgui" and "ui::commandline"
- "Manipulation", it is impossible to understand what it is being
manipulated with just a one-layer folder structure.
True. Each folder will have a README to explain what is in the folder. I can't think of a better name.
- "Object", it is impossible to understand what an "object" is in this
application without reading the code.
This is the name we've always used. I can't think of a better one. It's explained in the README.
The README solution sounds like a good trade off at this point in time.
- "extensions", what is the difference between a functionality
implemented as an extension and right away in the core of the application? In my opinion the word "extension" is to vague.
I agree with this. Will bring it up for discussion today.
- "libraries" folder, 3rd party libraries included as source code, this
is good idea but shouldn't 3rd party lib folder be next to "src" not inside it?
I'll bring this up for discussion.
I did a quick example on the Inkscape wiki [3]. This is just an idea and I'm not sure how feasible it is for Inkscape as I don't understand the codebase that good. The main idea is that business logic, that is SVG functionality goes into "core". The core parts knows nothing about the entrypoints (gui, command line, http API) nor data providers (file system, in-memory data storage).
[1] https://8thlight.com/blog/uncle-bob/2011/09/30/ Screaming-Architecture.html [2] https://www.slideshare.net/mattiabattiston/real-life- clean-architecture-61242830 - One example on how "screaming architecture" could be implemented. [3] http://wiki.inkscape.org/wiki/index.php/Source_Directory_ Structure_Screaming_Architecture
On Thu, Mar 29, 2018 at 07:30:13PM +0200, Christoffer Holmstedt wrote:
2018-03-29 13:35 GMT+02:00 Tavmjong Bah <tavmjong@...8...>:
Hi Christoffer,
Thanks for your input!
On Thu, 2018-03-29 at 12:14 +0200, Christoffer Holmstedt wrote:
It has been a year or two since I touched the Inkscape codebase but have recently been introduced to the idea of a "Screaming architecture by Robert C. Martin/Uncle Bob" [1, 2] in other development efforts and started to practice it. It might not be doable right now for Inkscape but goes along the idea that we want WITH_UI flag in the build system (be able to build headless inkscape that is). Also it should make it easier for new developers to understand the codebase just by looking at the file/directory structure.
Interesting ideas, which I mostly agree with. The problem, I think, is that truly descriptive names are going to be too long.
Yea, that is for sure my experience as well. It is a trade off between longer more descriptive names or putting the information in documentation somehow.
It's a good point though that terms like 'Object' and 'Item' and so on can have project-specific contextualized meaning that will not be obvious to first-time readers. A top level glossary explaining the jargon might be a way to address that need without having to come up with overly long names.
### Inside "src" folder There is nothing in the directory structure that clearly shows that this is an awesome SVG application.
- What is the difference between "display" and "ui"?
display is for drawing the SVG and controls on the canvas. Perhaps is should be renamed to 'render' or 'canvas'.
'render' seems good if it includes both the SVG and the controls. 'canvas'
implies only the SVG parts for me. In the end maybe that is what we want separated "render::canvas" and "render::controls"
We just discussed this terminology a bit further at the hackfest, and looked at some historical architectural documents.
- Is "ui" a gui or also command line?
Both.
For me it sounds like those should probably be separated "ui::gtkgui" and "ui::commandline"
Long term, I think we need to plan for a diversity of interfaces, including not only our current GUI and current command line, but perhaps new kinds of interfaces built atop a GAction-based API.
Since presently we don't have specific items to go under commandline, it could be left out for now.
Bryce
On Thu, Mar 29, 2018 at 01:47:05PM +0200, Tavmjong Bah wrote:
On Wed, 2018-03-28 at 21:28 +0200, Marc Jeanmougin wrote:
good proposal overall!
I'd make some changes & remarks though (I think there are a bit too many folders):
2geom -> libraries/2geom
We plan on moving this out of Inkscape.
extension -> extensions
This is the current name. 'extensions' might be better but...
io -> extensions/io
See doctormo's reply.
manipulation/knots -> ui/knot-manipulation
Will have to look at what is actually inside.
manipulation/misc -> manipulation/ manipulation/chemistry -> manipulation/ manipulation/selection -> manipulation/
Could evolve to this once things are cleaned up.
packaging -> ../packaging (same as now)
Everyone agrees, mistake on my part.
- What's the point of display/control ?
There are quite a few files for drawing controls (nodes, control lines) that have nothing to do with rendering SVG.
We discussed the name a bit, 'control' might be the wrong word as this is more about how control elements are _displayed_ and not how they _behave_ and "control" may imply more the latter. Looking through code and docs I think we saw 'CanvasItem' as existing jargon.
Bryce
participants (8)
-
Bryce Harrington -
Christoffer Holmstedt -
Eduard Braun -
Marc Jeanmougin -
Martin Owens -
Miguel Lopez -
Tavmjong Bah -
Ted Gould