CANopenNode
More documentation
I'd like docs for contribution rules (often a file CONTRIBUTING.md) (even if such rules are greatly permissive). I'd also like docs for how to deploy / recompile the project (for contribution purposes and more like supported platforms etc...).
Also are the CLI's commands documented somewhere ?
no, but if you run it without any parameters it will print it how to use it. Its basically the text below, but the list of export formats is generated at runtime
https://github.com/CANopenNode/CANopenEditor/blob/d3773bcf112553d6d55a8b5efc23b89c577e7746/EDSSharp/Program.cs#L177-L183
Tried to suggest a small rework of this help message in #192 and some more user help in #193. Do you want me to try and tackle this issue ?
Any help that advances this project is very welcome.
Documentation is not necessarily everyone's cup of tea. It is therefore always good when someone can be found who is committed to this area.
Many thanks
As strange as it may seem, I love making documentation. For this project, I would first need to get out my windows PC and test the GUIs to better understand it all but yes I'd like to do the docs haha.
Do you have any constraints for contribution rules ?
This is only my thoughts btw:
- Try to follow Common C# code conventions
- Dont just white-space format old code you don't touch, if you want you do that in its own pr. and add it to git-ignore. If you don't it messes up blame and that is very important in a project like this that done have a loot of tests.
- Please create a issue and to discuss before major changes/refactor, this makes it easier to avoid stepping on each others "toes"
- Keep a civil tone and lets work together.
- Try to add unit tests when you change/add something :)
Do you want to add a linter to this project ? Suggest its use or simply add it to the CI/CD ?
Do you want to add a linter to this project ? Suggest its use or simply add it to the CI/CD ?
Again this is my personal opinion, but i think we only need dotnet format and that should be added to ci/cd when code is ready. Not sure if formatting can be integrated into the c# project build process, but might be wrong here.
Other linter like systems can be integrated into the build process so contributors should not have to do anything other making sure it builds without errors. Hoping to use it on gui2 and eventually the other c# projects when the code is ready for it.
Version 1 of the contributing guidelines is on the PR if anyone wanna give an opinion.
As far as blame goes, neither pictures nor todos seem up to date (even the contributor's list is 4 years old...). Can I remove those three ? My personal opinion is that pictures shall be updated and put in other sections and the rest doesn't fit a README.
Just pushed a major refactor of the READMEs to my draft. Some PATHs are absolute but we can't really make them relative because we can read the main README from here: https://github.com/CANopenNode/CANopenEditor/tree/main and here: https://github.com/CANopenNode/CANopenEditor/blob/main/README.md and the second link is one subdir beyond the first one.
I think now we just need to write "how to use" for each project and we'll have a pretty good global documentation !
Is the todo list of the readme up to date ? Does someone use it ?
It still needs to be done, but it might be better to add them to a issue instead of a documentation file in my meaning. Dont think anyone uses it.
As far as blame goes, neither pictures nor todos seem up to date (even the contributor's list is 4 years old...). Can I remove those three ? My personal opinion is that pictures shall be updated and put in other sections and the rest doesn't fit a README.
With the exception of the contributor list it dont see a problem. What do you think about removing the contributor list (and the rest) @trojanobelix ?
I think now we just need to write "how to use" for each project and we'll have a pretty good global documentation !
Nice!
Personally, I don't need it. If anything, it should be automated via Contributors Readme Action Table with a link to the statistics .
If anything, it should be automated via Contributors Readme Action Table with a link to the statistics .
Love this idea !
Also, about dotnet run on Linux:
You seem to agree that it is to be discouraged but:
-
msccompiler have to run using mono and only supports C# up to 7.0 (we use default literals which came with 7.1) -
cschave troubles compiling, linking and stuff and isn't really well documented -
dotnet builddoes work butdotnet rundoesn't do much more than build then execute anyways...
Example of how we can use it with let's say a Makefile:
build_CLI:
dotnet build EDSSharp/EDSSharp.csproj
chmod +x EDSSharp/bin/Debug/net481/EDSSharp.exe
CLI:
./EDSSharp/bin/Debug/net481/EDSSharp.exe
-> If we add build_CLI as a dependency of CLI, we basically reinvented dotnet run. -> Make have trouble seing things as up to date with this setup and will always rerun build_CLI, even as a dependency, even if it is up to date.
How do you do yourselves ?
If anything, it should be automated via Contributors Readme Action Table with a link to the statistics .
Made it work on my fork. I'd like to separate those who maintain actively the project and have merge access for PRs (basically @nimrof and @trojanobelix haha) from the rest: Am I right by saying that the collaborator's list shall be just that (with maybe the CANopenNode account and Robin Cornelius) or shall I hardcode this maintainers list ? Also do you prefer using real names or usernames ?
Usernames prefered.
File list Perhaps we should divide the file formats into thematic areas using a blank line (CiA Docs, Extended Formats, CANopenNode Specific, Documentation) and describe them briefly:
EDS – Electronic Data Sheet according CiA 306-1 [.eds] DCF – Device Configuration File according CiA 306-1 [.dcf] XDD – XML Device Description V1.0/V1.1 according CiA 311 XDC – XML Device Configuration according CiA 311
NXDD – Network XML Device Description NXDC – Network XML Device Configuration XPD – XML Profile Description
CanOpenNode - CanOpenNode Object directory files [.h,.c] CanOpenNodeProtobuf - PCanOpenNode roject file [.json]/[.binpb]
DocumentationHTML [.html] DocumentationMarkup [.md] NetworkPDOReport [.md]
Shall we also add our own code of conduct or is it too much ? XD
Too much, in my opinion. Only a very limited number of people will be involved in this particular project at any given time. Therefore, we should focus on the most important information in order to keep the entry threshold low.
File list Perhaps we should divide the file formats into thematic areas using a blank line (CiA Docs, Extended Formats, CANopenNode Specific, Documentation) and describe them briefly
Done : https://github.com/CANopenNode/CANopenEditor/pull/194/commits/19081985290d96bfee953ae0707454d7e8cd19e7 Didn't find any exporter for .xpd tho...
About this whole "how to use" / compilation / dotnet run / ... thing: I guess you guys use Visual Studio Code right ? If so, is it really such a great idea to write "how to use" in the READMEs if it is to say "check this VS tutorial I found" ? As for Linux users, other methods as shell scripts or Makefiles might be used to automate most of it so shouldn't we just keep a small how to use in the main README (basically saying either use the .nsi, VS Code or the scripts) ? Another way might be making a cross-platform python script to use all of the projects but with the .nsi, I think windows users will have very limited use of such script and all might not know how to use it. Really not sure of where to go with this but if you think we souldn't put such stuff in the documentation I can make my PR ready for review and merging haha.
About this whole "how to use" / compilation / dotnet run / ... thing: I guess you guys use Visual Studio Code right ?
I use visual studio code and "full" vs as vs code does not work with winform.
If so, is it really such a great idea to write "how to use" in the READMEs if it is to say "check this VS tutorial I found" ?
Very much agree with you, but the idea is that users download the precompiled binary release or binary from a pull-request.
As for Linux users, other methods as shell scripts or Makefiles might be used to automate most of it so shouldn't we just keep a small how to use in the main README (basically saying either use the .nsi, VS Code or the scripts) ? Another way might be making a cross-platform python script to use all of the projects but with the .nsi, I think windows users will have very limited use of such script and all might not know how to use it. Really not sure of where to go with this but if you think we souldn't put such stuff in the documentation I can make my PR ready for review and merging haha.
I am open to different view here as long as we dont mix users that just want to make c/h files for canopennode and developers that want to help/change the code.
Sorry, but in not sure i understand your thoughts here. Your thinking that we should use .nsi installer for windows and a python script installer? for everything else?
Not really... I was thinking about this:
I think now we just need to write "how to use" for each project and we'll have a pretty good global documentation !
But you gave me an idea ! Releases come with a message so I think I'll just add a link to the latest release with a few instructions like "don't download source code" and that should be enough for users that need it (and we can always use release descriptions to give more instructions if needed).
Ok it's done. As suggested by @nimrof, the GUI's README might need a few pictures but after that I think we'll have a really solid documentation XD. Re requested review from @trojanobelix and will re request review from @nimrof when the pictures will be added (I think both approvals will be needed for such a huge change XD).