LDCad shadow library github repository

[Roland Melkert]

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

[Milan Vančura]

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

[Orion Pobursky]

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.

[Roland Melkert]

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.

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.

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

Sure, this is why i made a private one first. Once public I'll leave it up even if I stop working on it.

[Roland Melkert]

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?

[Max Murtazin]

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

[Orion Pobursky]

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.

[Milan Vančura]

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?

[Travis Cobbs]

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.

[Roland Melkert]

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.

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.

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

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?

[Orion Pobursky]

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

[Travis Cobbs]

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.

[Roland Melkert]

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

[Nils Schmidt]

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?

[Roland Melkert]

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.

[Roland Melkert]

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?

[Milan Vančura]

Any thoughts?

It looks very, very well!

[Roland Melkert]

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

[Max Murtazin]

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

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

[Roland Melkert]

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.

[Orion Pobursky]

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.

[Max Murtazin]

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