LDraw.org Discussion Forums
LDCad shadow library github repository - Printable Version

+- LDraw.org Discussion Forums (https://forums.ldraw.org)
+-- Forum: LDraw Programs (https://forums.ldraw.org/forum-7.html)
+--- Forum: LDraw Editors and Viewers (https://forums.ldraw.org/forum-11.html)
+--- Thread: LDCad shadow library github repository (/thread-26553.html)

LDCad shadow library github repository - Roland Melkert - 2022-07-10

Like discussed elsewhere, I'm considering starting a public github repository for the LDCad shadow library.

For this I would like some feedback about how to do this best.

I really could use some help deciding about the following things:

- License type
I'm currently using "Free for non commercial use" in all the .dat files, I've decided to change that to something more permissive like "CC BY-SA 4.0" but if someone has an alternative suggestion I'm open to that too.
The problem with this is I will need to contact the people whom contributed shadow info over the years (they are all members of the forum though Smile )
But worst-case scenario I'll just leave those files out (just about 400 .dat's in total or so)

- Author / change tracking.
Currently I only have a single Author line, but I figure a public repo needs some more information.
I really don't want a part tracker level of tracking, but I guess there should be some rules header wise.


I already made a private repository to do some tests with, so once a license is chosen it will be ready to go.

I also want to add some tools to LDCad to help format / maintain shadow info intended to be donated to the repo.


Any ideas/suggestions about how to get this repo/project started are welcome.

RE: LDCad shadow library github repository - Milan Vančura - 2022-07-11

My experience, a technical summary:

1. It's good, if not necessary, to agree on one license used for all shadow files, otherwise I cannot imagine what to do if, for example, I edited a file originally started by you.

2. CC BY-SA is very good idea, I believe. In general, it's much better to set a condition for next distribution than for noncommercial usage. For many reasons and one of the important ones is that open-source world does not always like the "non-commercial" clause. For example I could not put LDCAD into Build Service because this violates their conditions for projects. I had these problems when I tried to prepare ldraw packages for Linux users.

I believe CC BY-SA is OK in open-source world but please check it, to be 101% sure. Including github but not limited to.

3. If we agreed on one license, I think "0 !HISTORY" lines are enough to track each file life.

4. repository should contain files in exactly same format LDCAD knows both to read and write. For example line endings - LDCAD generates files with CRLF line endings so the repo should contain them this way. It's a pain to think about conversions all the time, although git helps with that.

5. if you start your git repo, please promise you do not delete it a day after Big Grin

RE: LDCad shadow library github repository - Orion Pobursky - 2022-07-11

(2022-07-11, 11:52)Milan Vančura Wrote: 4. LDCAD generates files with CRLF line endings

CRLF is required by the LDraw spec. While there isn't any obligation to follow the spec for non-library files, I think this is a good idea for interoperability.

RE: LDCad shadow library github repository - Roland Melkert - 2022-07-11

(2022-07-11, 11:52)Milan Vančura Wrote: I believe CC BY-SA is OK in open-source world but please check it, to be 101% sure. Including github but not limited to.
There are other projects on github using it, and it did recognize it after i uploaded the license.md file.

Only thing I'm not sure about is how it would affect packing the library as a .csl together with LDCad like it is used now.

(2022-07-11, 11:52)Milan Vančura Wrote: 4. repository should contain files in exactly same format LDCAD knows both to read and write. For example line endings - LDCAD generates files with CRLF line endings so the repo should contain them this way. It's a pain to think about conversions all the time, although git helps with that.
Like Orion wrote dos endings are an LDraw thing. Both the windows and Linux version of LDCad will read both endings but writes dos ones.

Git for windows asked what to do with endings during its setup. I did set it to 'no conversions' but I'm not sure how to force it on github.

(2022-07-11, 11:52)Milan Vančura Wrote: 5. if you start your git repo, please promise you do not delete it a day after Big Grin
Sure, this is why i made a private one first. Once public I'll leave it up even if I stop working on it.

RE: LDCad shadow library github repository - Roland Melkert - 2022-07-15

(2022-07-11, 21:10)Roland Melkert Wrote: Only thing I'm not sure  about is how it would affect packing the library as a .csl together with LDCad like it is used now.

I'm still stuck on this (seems to be the same for BY and BY-SA though).

It seems with version 4.0 it's enough to just mention the url of the repository somewhere.

But I'm not sure how a .csl will fit into this, unless I put the csl file itself in the repository too?

Any thoughts on this?

RE: LDCad shadow library github repository - Max Murtazin - 2022-07-15

Well, is there anything wrong with putting .csl in the directory?

RE: LDCad shadow library github repository - Orion Pobursky - 2022-07-15

You don't have to have a link back if you (or your group) are the original source. Link backs are required (most of the time) for those who create derivatives and are not affiliated with the original source.

RE: LDCad shadow library github repository - Milan Vančura - 2022-07-17

(2022-07-15, 21:58)Roland Melkert Wrote: I'm still stuck on this (seems to be the same for BY and BY-SA though).

It seems with version 4.0 it's enough to just mention the url of the repository somewhere.

But I'm not sure how a .csl will fit into this, unless I put the csl file itself in the repository too?

Any thoughts on this?

What about answering by question: How this situation with csl differs to any other projects in git where source files only are stored in git (of course) and both compiled programs and archives of the project, which is how usual project is distributed then, are generated? Git contains a command for this, BTW, it's called 'git archive'.

I think it's normal and usual but I'm serious with my question: is there any important difference with csl?

RE: LDCad shadow library github repository - Travis Cobbs - 2022-07-17

(2022-07-15, 21:58)Roland Melkert Wrote: I'm still stuck on this (seems to be the same for BY and BY-SA though).

It seems with version 4.0 it's enough to just mention the url of the repository somewhere.

But I'm not sure how a .csl will fit into this, unless I put the csl file itself in the repository too?

Any thoughts on this?

Isn't this normally handled with a LICENSE.md file in the repository? All the files in the repository are then covered by that LICENSE.md file.

RE: LDCad shadow library github repository - Roland Melkert - 2022-07-17

(2022-07-15, 22:00)Max Murtazin Wrote: Well, is there anything wrong with putting .csl in the directory?
Not really but it will be outdated most of the time as it needs to be repacked (compiled if you will) after each change.

(2022-07-15, 22:49)Orion Pobursky Wrote: You don't have to have a link back if you (or your group) are the original source. Link backs are required (most of the time) for those who create derivatives and are not affiliated with the original source.
I guess so but a .csl is basically an optional dll. So putting it in the about box seemed somewhat strange to me.


(2022-07-17, 8:38)Milan Vančura Wrote: What about answering by question: How this situation with csl differs to any other projects in git where source files only are stored in git (of course) and both compiled programs and archives of the project, which is how usual project is distributed then, are generated? Git contains a command for this, BTW, it's called 'git archive'.

I think it's normal and usual but I'm serious with my question: is there any important difference with csl?
A .csl is just a zipped version of the parts and p folders just like complete.zip. So you could indeed see it as a release of the 'source'.


(2022-07-17, 18:28)Travis Cobbs Wrote: Isn't this normally handled with a LICENSE.md file in the repository? All the files in the repository are then covered by that LICENSE.md file.
Yes but if you use the project as a single .csl there is no (local) .md unless you unpack the .csl.


Maybe I'm overthinking this?

RE: LDCad shadow library github repository - Orion Pobursky - 2022-07-17

(2022-07-17, 19:02)Roland Melkert Wrote: Maybe I'm overthinking this?

I think you are. I think having it inside the archive is fine since the archive is just a delivery vehicle for the source contained within. If anyone wants to alter the source, they'll have to unpack the archive and will encounter the license file. As for your "outdated" concern, you can set up Github to automatically generate archive after every commit (at least I think you can).

RE: LDCad shadow library github repository - Travis Cobbs - 2022-07-18

(2022-07-17, 19:02)Roland Melkert Wrote: A .csl is just a zipped version of the parts and p folders just like complete.zip. So you could indeed see it as a release of the 'source'.

Then that would normally be done on GitHub using a release, and attached to that release. GitHub itself will automatically generate a zip and tgz of the repository itself as the "source release", and you would manually attach the csl file to the release as a downloadable binary. If the CSL really is just a different extension of a zip, it might not hurt to include a LICENSE.md inside.

RE: LDCad shadow library github repository - Roland Melkert - 2022-07-20

(2022-07-18, 23:18)Travis Cobbs Wrote: Then that would normally be done on GitHub using a release, and attached to that release. GitHub itself will automatically generate a zip and tgz of the repository itself as the "source release", and you would manually attach the csl file to the release as a downloadable binary. If the CSL really is just a different extension of a zip, it might not hurt to include a LICENSE.md inside.

It could be even easier, as downloading the repository trough its green code button already gives you a zip.

You could use that zip as-is if I make a minor change to LDCad's shadow loader (to compensate for the top level folder inside the zip).

RE: LDCad shadow library github repository - Nils Schmidt - 2022-07-20

(2022-07-20, 18:02)Roland Melkert Wrote: It could be even easier, as downloading the repository trough its green code button already gives you a zip.

You could use that zip as-is if I make a minor change to LDCad's shadow loader (to compensate for the top level folder inside the zip).

Maybe, it is also possible to use the "zip" filename extension instead of "csl" for the shadow library.
Then you could directly use the files provided by Github?

RE: LDCad shadow library github repository - Roland Melkert - 2022-07-20

(2022-07-20, 19:30)Nils Schmidt Wrote: Maybe, it is also possible to use the "zip" filename extension instead of "csl" for the shadow library.
Then you could directly use the files provided by Github?

The archive doesn't need to be .csl, I use that mainly to make clear it's not a normal part library zip.

RE: LDCad shadow library github repository - Roland Melkert - 2022-07-21

I've gotten the ok from all contributors to change the license to CC-BY-SA 4.0

Last thing I need to do to get this going is mass edit all files.

For this I need to setup the generic header format/rules.

At the moment I'm thinking something like this:

Code:
0 LDCad info for "Technic Axle Hole Semi-Reduced Perimeter"
0 !LICENSE CC-BY-SA 4.0, see LICENSE.md
0 !HISTORY 2022-07-19 {Roland Melkert} Initial info for p/axl3hol8.dat

0 //Axle, will be scaled in higher references as long only the y axle is scaled.
0 // center=false and non zero pos here, because the primitive isn't centered at 0,0,0 which would cause displacement due to scaling.
0 // Use an ID so unwanted axle info can be dropped in higher parts using a more complicated composed hole.
0 !LDCAD SNAP_CYL [id=axleHole3] [gender=F] [caps=none] [secs=A 6 1] [slide=true] [pos=0 1 0] [scale=YOnly]

Main things:
- No (main) AUTHOR line as there could be many.
- No NAME line because file names can change resulting from LDraw 'moved to' changes (change should be listed in a history line).

Any thoughts?

RE: LDCad shadow library github repository - Milan Vančura - 2022-07-21

(2022-07-21, 19:45)Roland Melkert Wrote: Any thoughts?

It looks very, very well!

RE: LDCad shadow library github repository - Roland Melkert - 2022-07-23

(2022-07-21, 19:45)Roland Melkert Wrote: Last thing I need to do to get this going is mass edit all files.

I've made some changes to the (currently dev version only) shadow validator inside LDCad.

It now forces this:
Code:
0 LDCad shadow info for "Stud"
0 Author: LDCad Shadow Library
0 !LICENSE CC-BY-SA 4.0, see LICENSE.md
0 !HISTORY 2022-07-23 {Roland Melkert} Initial info for stud.dat

0 !LDCAD SNAP_CYL [ID=studC] [gender=M] [caps=one] [secs=R 6 4]

Still not sure about the author line though.

And maybe add an empty line before the history (like LDraw part headers).

I also would like a 'real' first info date. But most of the files have a creation date of 2020-04-06 because that's when I copied the 1.7 branch from 1.6 Big Grin

RE: LDCad shadow library github repository - Max Murtazin - 2022-07-23

(2022-07-23, 22:11)Roland Melkert Wrote: I've made some changes to the (currently dev version only) shadow validator inside LDCad.

It now forces this:
Code:
0 LDCad shadow info for "Stud"
0 Author: LDCad Shadow Library
0 !LICENSE CC-BY-SA 4.0, see LICENSE.md
0 !HISTORY 2022-07-23 {Roland Melkert} Initial info for stud.dat

0 !LDCAD SNAP_CYL [ID=studC] [gender=M] [caps=one] [secs=R 6 4]

Still not sure about the author line though.

And maybe add an empty line before the history (like LDraw part headers).

I also would like a 'real' first info date. But most of the files have a creation date of 2020-04-06 because that's when I copied the 1.7 branch from 1.6 Big Grin

Does LDCad even require an author line? If not, just no reason to keep it at all then

RE: LDCad shadow library github repository - Roland Melkert - 2022-07-23

(2022-07-23, 22:14)Max Murtazin Wrote: Does LDCad even require an author line? If not, just no reason to keep it at all then

LDCad doesn't need any of the header lines, it only really cares about "0 !LDCAD SNAP" ones

Downside of open source (imho) is all the extra needed 'paper work' hence these headers.

I just want to be sure about them before committing it all and making the repository public because I don't want these headers to change often (as they will cause a diff nightmare).

Using the repository as the generic author might be easier when people need to attribute it.

RE: LDCad shadow library github repository - Orion Pobursky - 2022-07-23

(2022-07-23, 22:14)Max Murtazin Wrote: Does LDCad even require an author line? If not, just no reason to keep it at all then

I would say the author is tracked by commit or commit comment so author is not needed at all.

RE: LDCad shadow library github repository - Max Murtazin - 2022-07-23

(2022-07-23, 22:44)Orion Pobursky Wrote: I would say the author is tracked by commit or commit comment so author is not needed at all.

Exactly why I say that, all contributions are tracked without author line, so if there are no technical requirements for that line, better to drop it