Recent changes to Developer Community Documentation

Developer Community Documentation modified by aliazzz

aliazzz — Wed, 16 Sep 2020 07:50:37 -0000

--- v20
+++ v21
@@ -27,6 +27,7 @@

 The demos are running 2h and can be restarted as often as you want.
 These can also run demos of fieldbus stacks, which will run for 30m before a restart is needed.
+

 ## Version Control System
 You should use SVN when you want to have a good version control system with CODESYS projects, and if you want to publish them on CODESYS Forge.
@@ -140,5 +141,6 @@
     The tips and practices laid out in the CODESYS help are pretty complete but not as thorough as Steve McConnell "Code Complete", though they provide a very good starting point. 
     For further reading see e.g. **Steve McConnell "Code Complete"**;

-# Forge tips
+# Forge Tips
 * If you want to experiment with markdown syntax, create a project on your profile called "internaltest" and take away permissions of everyone but you.
+* Use the "Create..." button in the top right menu bar for easy access of a wizard for creating and sharing community driven content.

Developer Community Documentation modified by aliazzz

aliazzz — Wed, 16 Sep 2020 07:47:09 -0000

--- v19
+++ v20
@@ -134,7 +134,7 @@
 - when using RTS_IEC_HANDLE and RTS_IEC_RESULT types, please add SysTypes2 Interfaces (3.5.4.0);
 - if possible, use standard error codes (CmpErrors or CmpErrors2 Interfaces);
 - if possible, avoid using dynamic memory (the usage of NEW operator);
-- usage of **Structured Text (IEC-ST)** language is trongly encouraged whenever possible as ST is by far the most versatile language in which all operations manipulations and functions are possible;
+- usage of **Structured Text (IEC-ST)** language is highly encouraged whenever possible. ST is by far the most versatile and universal language in which all operations manipulations and functions are possible;
 - document the source code, add meaningful comments to it;
 - for modern coding style advice: read the CODESYS v3 library development tips as provided in [CODESYS help](https://help.codesys.com/webapp/_cds_guidelines_for_creating_libraries;product=codesys;version=3.5.15.0),
     The tips and practices laid out in the CODESYS help are pretty complete but not as thorough as Steve McConnell "Code Complete", though they provide a very good starting point.

Developer Community Documentation modified by aliazzz

aliazzz — Wed, 16 Sep 2020 07:46:02 -0000

--- v18
+++ v19
@@ -134,7 +134,7 @@
 - when using RTS_IEC_HANDLE and RTS_IEC_RESULT types, please add SysTypes2 Interfaces (3.5.4.0);
 - if possible, use standard error codes (CmpErrors or CmpErrors2 Interfaces);
 - if possible, avoid using dynamic memory (the usage of NEW operator);
-- always use Structured Text (ST) language whenever possible as ST is by far the most versatile language, in which all operations, manipulations and functions are possible;
+- usage of **Structured Text (IEC-ST)** language is trongly encouraged whenever possible as ST is by far the most versatile language in which all operations manipulations and functions are possible;
 - document the source code, add meaningful comments to it;
 - for modern coding style advice: read the CODESYS v3 library development tips as provided in [CODESYS help](https://help.codesys.com/webapp/_cds_guidelines_for_creating_libraries;product=codesys;version=3.5.15.0),
     The tips and practices laid out in the CODESYS help are pretty complete but not as thorough as Steve McConnell "Code Complete", though they provide a very good starting point.

Developer Community Documentation modified by aliazzz

aliazzz — Wed, 16 Sep 2020 07:44:44 -0000

--- v17
+++ v18
@@ -1,8 +1,12 @@
 [TOC]

 # Community
-This documentation is open to be edited by all CODESYS Forge developers. It can be used to share global information, which is of interest for developers of differnt projects.
-The contents is **not** meant as dogmatic and should provide the reader with enough tips & tricks to help write code which is clearly readable and quicker understood by the community. The developer adhering to these tips & tricks, in return, will reap the benefits in an obvious manner. So, following tips & tricks is strongly encouraged!
+This documentation is open to be edited by all CODESYS Forge developers. 
+The documentation is intended to share global information, which is of interest for developers of different projects.
+
+The contents of the documentation is **not meant dogmatic** and should provide the reader with enough tips & tricks to help write code which is clearly readable and quicker understood by the community. 
+
+**The developer adhering to these tips & tricks, in return, will reap the benefits in an obvious manner. So, following tips & tricks is strongly encouraged!**

 * Software hints
 * Workflows

Developer Community Documentation modified by i-campbell

i-campbell — Fri, 24 Apr 2020 21:37:11 -0000

--- v16
+++ v17
@@ -135,3 +135,6 @@
 - for modern coding style advice: read the CODESYS v3 library development tips as provided in [CODESYS help](https://help.codesys.com/webapp/_cds_guidelines_for_creating_libraries;product=codesys;version=3.5.15.0),
     The tips and practices laid out in the CODESYS help are pretty complete but not as thorough as Steve McConnell "Code Complete", though they provide a very good starting point. 
     For further reading see e.g. **Steve McConnell "Code Complete"**;
+    
+# Forge tips
+* If you want to experiment with markdown syntax, create a project on your profile called "internaltest" and take away permissions of everyone but you.

Developer Community Documentation modified by i-campbell

i-campbell — Mon, 18 Nov 2019 21:59:58 -0000

--- v15
+++ v16
@@ -2,7 +2,7 @@

 # Community
 This documentation is open to be edited by all CODESYS Forge developers. It can be used to share global information, which is of interest for developers of differnt projects.
-The contents is **not** ment dogmatic and should provide the reader with enough tips & tricks to help write code which is clearly readable and quicker understood by the community. The developper adhering to these tips & tricks, in return, will reap the benefits in an obvious manner. So, following tips & tricks is strongly encouraged!
+The contents is **not** meant as dogmatic and should provide the reader with enough tips & tricks to help write code which is clearly readable and quicker understood by the community. The developer adhering to these tips & tricks, in return, will reap the benefits in an obvious manner. So, following tips & tricks is strongly encouraged!

 * Software hints
 * Workflows
@@ -22,11 +22,14 @@
 * CODESYS Control for Linux SL

 The demos are running 2h and can be restarted as often as you want.
+These can also run demos of fieldbus stacks, which will run for 30m before a restart is needed.

 ## Version Control System
 You should use SVN when you want to have a good version control system with CODESYS projects, and if you want to publish them on CODESYS Forge.

 CODESYS SVN can be freely used with CODESYS Forge. But we reconnend to use the tool [cforge](/tol/cforge), as it improves the workflow with CODESYS Forge pretty much.
+
+CODESYS Git is expected to be available in the next SP.

 # Versioning

@@ -37,7 +40,7 @@

 Things like the compiler version, visu profile, etc. will usually be used from the final project, not from the library. 

-Offcourse there are some known exceptions;
+Of course there are some known exceptions;
 * ;
 * ;
 * etc
@@ -93,9 +96,35 @@

 As seen, this versioning scheme leaves "room" for (arbitrarily) smaller or larger code updates while also providing a clear overview of the development progress.

-Offcourse, other versioning scheme's are possible (provide examples).
+Of course, other versioning scheme's are possible (provide examples).

-  
+### A versioning scheme I have used successfully for machines is this:
+  Vx.y.z
+I will start in the middle as that is the most important, the state.
+y = 0 = concept (just messing around with an idea)
+y = 1 = development (goal in mind)
+y = 2 = released for internal testing (devoloper thinks they are finished and are ready to run through internal testing)
+y = 3 = released for stakeholder testing (testing complete, ready for testing with eg. Customer or product owner)
+y = 4 = released for site (this version has all the testing and is ready for site)
+y = 5 = installed on site (this version is installed on site, but is either not working or hasn't been tested)
+y = 6 = commissioned (installed on site and somebody (customer?) is satisfied that it is working)
+
+Now let's look to the least significant, version z. The first time you enter a new state you are on z=0. Any commits in that state, and z=z+1; Easy right?
+
+Now the most significant, version x. The rule is "you cannot go backwards in y without incrementing x."
+
+So that is the rules all covered. Now to some nuances or "what about when...".
+
+Say you are in V0.3.0 (first stakeholder testing version) and the customer says "I want red to mean on". You do not need to go back to development stage or internal testing. You can simply make the change and commit as "V0.3.1 red now means on", then continue testing.
+But what if next they said "you completely forgot the intake section of the machine specification!" Perhaps they threw the acceptance test sheets into the air and stormed out of the room. You can probably understand the state (y) may need to go back to development. So, your next commit is V1.1.0.
+
+OK, so fast forward to commissioning. It is day 3 of commissioning and you are on V1.5.14. The customer is happy. You now make a commit (with no code changes from V1.5.14) to V1.6.0. The commit message might say something like "customer happy with site test" or even "developer happy the software is working" if that's how you run things.
+
+A couple months later the customer asks "can you add an OFF delay to input 3?" You come round, do the change online, customer tests it and says it is fine. Just use V1.6.1 for your next commit.
+
+A further 3 months and another small change is asked for. "We would like a trend of input 6." You go in on a down day, make the software change, but there's no product so you can't really test it. Commit the change as V2.5.0 (y=5, increase x by 1, reset z to zero).  Two days later you check in with the customer. "All is good". Now you get a new commit, V2.6.0.
+
+It is possible to skip steps as well. e.g. If it's decided a Factory Acceptance Test (y=3) isn't needed, go straight to 4.

 # Coding tips
 - when using RTS_IEC_HANDLE and RTS_IEC_RESULT types, please add SysTypes2 Interfaces (3.5.4.0);
@@ -103,6 +132,6 @@
 - if possible, avoid using dynamic memory (the usage of NEW operator);
 - always use Structured Text (ST) language whenever possible as ST is by far the most versatile language, in which all operations, manipulations and functions are possible;
 - document the source code, add meaningful comments to it;
-- for modern coding style advice: read the CODESYS v3 library development tips as provided in [CODESYS help](https://help.codesys.com/webapp/Guidelines_for_creating_libraries;product=codesys;version=3.5.13.0),
+- for modern coding style advice: read the CODESYS v3 library development tips as provided in [CODESYS help](https://help.codesys.com/webapp/_cds_guidelines_for_creating_libraries;product=codesys;version=3.5.15.0),
     The tips and practices laid out in the CODESYS help are pretty complete but not as thorough as Steve McConnell "Code Complete", though they provide a very good starting point. 
     For further reading see e.g. **Steve McConnell "Code Complete"**;

Developer Community Documentation modified by aliazzz

aliazzz — Sat, 05 Oct 2019 20:32:19 -0000

--- v14
+++ v15
@@ -105,9 +105,4 @@
 - document the source code, add meaningful comments to it;
 - for modern coding style advice: read the CODESYS v3 library development tips as provided in [CODESYS help](https://help.codesys.com/webapp/Guidelines_for_creating_libraries;product=codesys;version=3.5.13.0),
     The tips and practices laid out in the CODESYS help are pretty complete but not as thorough as Steve McConnell "Code Complete", though they provide a very good starting point. 
-    For further reading see e.g. Steve McConnell "Code Complete";
-
-# External References
-The following is a list of some greate resources about some more advanced programming techniques.
-
-* [Stefan Hennekens Blog](https://stefanhenneken.wordpress.com)
+    For further reading see e.g. **Steve McConnell "Code Complete"**;

Developer Community Documentation modified by aliazzz

aliazzz — Fri, 28 Dec 2018 11:32:35 -0000

--- v13
+++ v14
@@ -48,13 +48,15 @@

      v0.0.0.1    Initial version: Your first library / project in beta stage

+ 
  whenever you code or bugfix just arbitrarily count up as you see fit, there is no right or wrong;

      v0.0.0.2    Bugfixes/coding version 2
      ..
      v0.0.0.49   Bugfixes/coding version 49
      etc, etc.
-     
+ 
+ 
  whenever you have tested a complete stable internal version;

      v0.0.1.0    your first stable version (tested)
@@ -65,7 +67,8 @@
      ..
      v0.0.3.11   your third stable version (tested) with more bugfixes
      etc, etc.
-     
+
+
 whenever you have software which you have tested externally (public beta);

      v0.1.0.0    your first public beta version (tested/ publicly released)
@@ -74,6 +77,7 @@
      ..
      v0.2.0.0    your second public beta version (tested/ publicly released)
      etc, etc.
+     

 Whenever you have a stable public alpha release;

@@ -85,6 +89,7 @@
      ..
      v2.0.0.0    Your second alpha released version
      etc, etc.
+ 

 As seen, this versioning scheme leaves "room" for (arbitrarily) smaller or larger code updates while also providing a clear overview of the development progress.

Developer Community Documentation modified by aliazzz

aliazzz — Fri, 28 Dec 2018 11:31:52 -0000

--- v12
+++ v13
@@ -48,14 +48,14 @@

      v0.0.0.1    Initial version: Your first library / project in beta stage

- whenever you bugfix, just count up..
+ whenever you code or bugfix just arbitrarily count up as you see fit, there is no right or wrong;

      v0.0.0.2    Bugfixes/coding version 2
      ..
      v0.0.0.49   Bugfixes/coding version 49
      etc, etc.

- whenever you have tested a complete stable internal version
+ whenever you have tested a complete stable internal version;

      v0.0.1.0    your first stable version (tested)
      ..
@@ -66,7 +66,7 @@
      v0.0.3.11   your third stable version (tested) with more bugfixes
      etc, etc.

-whenever you have software which you have tested externally (public beta)
+whenever you have software which you have tested externally (public beta);

      v0.1.0.0    your first public beta version (tested/ publicly released)
      ..
@@ -75,7 +75,7 @@
      v0.2.0.0    your second public beta version (tested/ publicly released)
      etc, etc.

-Whenever you have a stable public aplha release;
+Whenever you have a stable public alpha release;

      v1.0.0.0    Your first alpha released version
      ..
@@ -88,7 +88,7 @@

 As seen, this versioning scheme leaves "room" for (arbitrarily) smaller or larger code updates while also providing a clear overview of the development progress.

-Offcourse, other versioning scheme's are possible (provide examples)
+Offcourse, other versioning scheme's are possible (provide examples).

Developer Community Documentation modified by codesys.com

codesys.com — Thu, 27 Dec 2018 20:07:53 -0000

--- v11
+++ v12
@@ -102,4 +102,7 @@
     The tips and practices laid out in the CODESYS help are pretty complete but not as thorough as Steve McConnell "Code Complete", though they provide a very good starting point. 
     For further reading see e.g. Steve McConnell "Code Complete";

+# External References
+The following is a list of some greate resources about some more advanced programming techniques.

+* [Stefan Hennekens Blog](https://stefanhenneken.wordpress.com)