From c1a4d62a55d25c4212bc40940e11b16372b57ef5 Mon Sep 17 00:00:00 2001 From: Jeno Vago Date: Sun, 14 Feb 2021 00:12:07 +0100 Subject: [PATCH 1/4] Collecting hopefully useful info for newly-joined contributors to start. --- README.beginner-developer | 72 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 README.beginner-developer diff --git a/README.beginner-developer b/README.beginner-developer new file mode 100644 index 000000000..5ed7a7f80 --- /dev/null +++ b/README.beginner-developer @@ -0,0 +1,72 @@ + This is some collection to help recently joined coders to start with. + You can try the hard way. Then you just do not need to read any further. + Beleive me, at least for me, adds unnecessary frustration. + You lean back, feeling as (almost) on top of the World -- just to have to + learn somewhat later when asking for merge your work, that you are far from done... + + In spite of every effort, this doc will (and can) never become complete. + Any comments, critisisms, suggestions, improvement requests are + and will a l w a y s and f o r e v e r remain W E L C O M E . + + To begin with, each project using any computer language, ususally is built upon + - partly some project conventions + - partly some personal tastes. + + Individual tastes are no problem for one-man projects. + However, for bigger and long-lasting projects, individual tastes obviously + do not help readibility or maintenability. + My personal note, IMHO project conventions are also mainly of + personal taste of somebody in the project much before you joined ;-) ... + + The following is the list we could collect so far. + This list is only numbered for easy reference. + This list is not considered to be sorted upon importance, + nor do I think there could be any such importance. + Please never re-number this list. + In case anybody feels in absolute need of picking some points upon importance, + please simply use a list in the header immediately below this introduction, like: + +important by HA5SE: 1, 2, 3 // sample + + + +Currently documented conventions +================================ + + +1) TLF is a combination of old code mixed with many new updates. + Old code is as-is, you should never count on conventions in old + code would still continue to be considered as current. + + Recent code uses different conventions. + + Code is considered old when before ... + + You can check the age of any line or block using + + git blame ... + + +2) No need to update Changelog . It only will be updated once for all changes so far + for each single new release by the maintainer. [thanks to HA5CQZ] + + +3) In turn, it is your responsibility to update the manual page tlf.1.in if your contribution + brings in visible changes to end-users. Such changes include e.g. new config keywords. + + +4) Do not include your callsign or reason or similar in your modification. [thanks to HA5CQZ] + No need to anything like + + // 2021-02-01 HA5SE implementing TUNE_LNG= + + Instead of comments like that, rather count on "git blame" + + +5) When defining global variables we have to choices: [thanks to DL1JBE] + + - Variables which are only part of an module should be defined in the module itself + and made known to other modules by declaring them extern in the modules header file + - Alternatively if the variable is not clearly related to a functional module we have + concentrated them in one place - at the moment in main.c (with test/data.c a shadow + copy for testing purposes). The variable should then be declared in globalvars.h From cdbefd4429fe9eec0c6a061eba54d2240dada737 Mon Sep 17 00:00:00 2001 From: Jeno Vago Date: Sat, 20 Feb 2021 20:19:17 +0100 Subject: [PATCH 2/4] Collecting hopefully useful info for newly-joined contributors to start, now md format. --- README.beginner-developer.md | 76 ++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 README.beginner-developer.md diff --git a/README.beginner-developer.md b/README.beginner-developer.md new file mode 100644 index 000000000..cc20d8fc5 --- /dev/null +++ b/README.beginner-developer.md @@ -0,0 +1,76 @@ +# Tlf ham radio contest logger + +## Summary + +This is some collection to help recently joined coders to start with contributing TLF. +You can try the hard way. Then you just do not need to read any further. +Beleive me, at least for me, added unnecessary frustration not knowing any such collection. +You lean back, feeling (almost) on top of the World -- just to have to +learn somewhat later when asking for merge your work, that you are far from done... + +In spite of every effort, this doc will (and can) never become complete. +Any comments, critisisms, suggestions, improvement requests are _ W E L C O M E . + +To begin with, each project using any computer language, ususally is built upon +* partly some project conventions +* partly some personal tastes. + +Individual tastes are no problem for one-man projects. +However, for bigger and long-lasting projects, individual tastes obviously +do not help readibility or maintenability. +My personal note, project conventions are also mainly built up of +personal taste of somebody in the project much before you joined ;-) ... + +The following is the list we could collect so far. +This list is only numbered for easy reference. +This list is not considered to be sorted upon importance, +nor do I think there could be any such importance. +Please never re-number this list, that is, only add new points at end of file. +In case anybody feels in absolute need of picking some points upon importance, +please simply use a list in the header immediately below this introduction, like: + +**`important by HA5SE: 1, 2, 3 // sample`** + + + +## Currently documented conventions + + +1) TLF is a combination of old code mixed with many new updates. + Old code is as-is, you should never count on conventions in old + code would still continue to be considered as current. + + Recent code often uses different conventions. + + Code is considered old when before ... + + You can check the age of any line or block using + + **`git blame ...`** + + +2) No need to update **` Changelog `** . It only will be updated once for all changes + per each single new release by the maintainer. [thanks to HA5CQZ] + + +3) In turn, it is your responsibility to update the manual page **` tlf.1.in `** if your contribution + brings in visible changes to end-users. Such changes include e.g. new config keywords. + + +4) Do not include your callsign or reason or similar in your modification. [thanks to HA5CQZ] + No need to insert anything like + + **`// 2021-02-01 HA5SE implementing TUNE_LNG=`** + + Instead of comments like that, rather count on + + **`git blame`** + + +5) When defining global variables we have two choices: [thanks to DL1JBE] + + * Variables which are only part of an module should be defined in the module itself + and made known to other modules by declaring them extern in the modules header file + * Alternatively if the variable is not clearly related to a functional module we have + concentrated them in one place - at the moment in **` main.c `** (with **` test/data.c `** a + shadow copy for testing purposes). The variable should then be declared in **` globalvars.h `** . From 4e746147b16b3a529f530bcef506d85a3a42c7a9 Mon Sep 17 00:00:00 2001 From: Jeno Vago Date: Thu, 25 Feb 2021 20:11:44 +0100 Subject: [PATCH 3/4] Delete non-md file, minor rephrasing --- README.beginner-developer | 72 ------------------------------------ README.beginner-developer.md | 3 +- 2 files changed, 2 insertions(+), 73 deletions(-) delete mode 100644 README.beginner-developer diff --git a/README.beginner-developer b/README.beginner-developer deleted file mode 100644 index 5ed7a7f80..000000000 --- a/README.beginner-developer +++ /dev/null @@ -1,72 +0,0 @@ - This is some collection to help recently joined coders to start with. - You can try the hard way. Then you just do not need to read any further. - Beleive me, at least for me, adds unnecessary frustration. - You lean back, feeling as (almost) on top of the World -- just to have to - learn somewhat later when asking for merge your work, that you are far from done... - - In spite of every effort, this doc will (and can) never become complete. - Any comments, critisisms, suggestions, improvement requests are - and will a l w a y s and f o r e v e r remain W E L C O M E . - - To begin with, each project using any computer language, ususally is built upon - - partly some project conventions - - partly some personal tastes. - - Individual tastes are no problem for one-man projects. - However, for bigger and long-lasting projects, individual tastes obviously - do not help readibility or maintenability. - My personal note, IMHO project conventions are also mainly of - personal taste of somebody in the project much before you joined ;-) ... - - The following is the list we could collect so far. - This list is only numbered for easy reference. - This list is not considered to be sorted upon importance, - nor do I think there could be any such importance. - Please never re-number this list. - In case anybody feels in absolute need of picking some points upon importance, - please simply use a list in the header immediately below this introduction, like: - -important by HA5SE: 1, 2, 3 // sample - - - -Currently documented conventions -================================ - - -1) TLF is a combination of old code mixed with many new updates. - Old code is as-is, you should never count on conventions in old - code would still continue to be considered as current. - - Recent code uses different conventions. - - Code is considered old when before ... - - You can check the age of any line or block using - - git blame ... - - -2) No need to update Changelog . It only will be updated once for all changes so far - for each single new release by the maintainer. [thanks to HA5CQZ] - - -3) In turn, it is your responsibility to update the manual page tlf.1.in if your contribution - brings in visible changes to end-users. Such changes include e.g. new config keywords. - - -4) Do not include your callsign or reason or similar in your modification. [thanks to HA5CQZ] - No need to anything like - - // 2021-02-01 HA5SE implementing TUNE_LNG= - - Instead of comments like that, rather count on "git blame" - - -5) When defining global variables we have to choices: [thanks to DL1JBE] - - - Variables which are only part of an module should be defined in the module itself - and made known to other modules by declaring them extern in the modules header file - - Alternatively if the variable is not clearly related to a functional module we have - concentrated them in one place - at the moment in main.c (with test/data.c a shadow - copy for testing purposes). The variable should then be declared in globalvars.h diff --git a/README.beginner-developer.md b/README.beginner-developer.md index cc20d8fc5..a42fa401d 100644 --- a/README.beginner-developer.md +++ b/README.beginner-developer.md @@ -42,7 +42,8 @@ please simply use a list in the header immediately below this introduction, like Recent code often uses different conventions. - Code is considered old when before ... + There is the possibility to find old, outdated conventions in old code before 200???? or V1??? + It is better to use examples in more recent code. You can check the age of any line or block using From 6198eb790c8b8a6a14d18ec7254f0e141c3848ab Mon Sep 17 00:00:00 2001 From: Thomas Beierlein Date: Tue, 16 Mar 2021 20:02:07 +0100 Subject: [PATCH 4/4] Minor corrections and clarifications --- README.beginner-developer.md | 45 ++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/README.beginner-developer.md b/README.beginner-developer.md index a42fa401d..49cde3855 100644 --- a/README.beginner-developer.md +++ b/README.beginner-developer.md @@ -2,14 +2,19 @@ ## Summary -This is some collection to help recently joined coders to start with contributing TLF. +started by HA5SE + +This is some collection to help recently joined coders to start with +contributing to TLF. You can try the hard way. Then you just do not need to read any further. -Beleive me, at least for me, added unnecessary frustration not knowing any such collection. +Believe me, at least for me, it added unnecessary frustration that there were +no such collection. You lean back, feeling (almost) on top of the World -- just to have to learn somewhat later when asking for merge your work, that you are far from done... In spite of every effort, this doc will (and can) never become complete. -Any comments, critisisms, suggestions, improvement requests are _ W E L C O M E . +Any comments, critisisms, suggestions, improvement requests are +_ W E L C O M E . To begin with, each project using any computer language, ususally is built upon * partly some project conventions @@ -40,10 +45,8 @@ please simply use a list in the header immediately below this introduction, like Old code is as-is, you should never count on conventions in old code would still continue to be considered as current. - Recent code often uses different conventions. - - There is the possibility to find old, outdated conventions in old code before 200???? or V1??? - It is better to use examples in more recent code. + Recent code often uses different conventions. Try to adapt your code to + the modern ones. You can check the age of any line or block using @@ -54,24 +57,32 @@ please simply use a list in the header immediately below this introduction, like per each single new release by the maintainer. [thanks to HA5CQZ] -3) In turn, it is your responsibility to update the manual page **` tlf.1.in `** if your contribution - brings in visible changes to end-users. Such changes include e.g. new config keywords. +3) In turn, it is your responsibility to update the manual page + **` tlf.1.in `** if your contribution + brings in visible changes to end-users. Such changes include e.g. new + config keywords. -4) Do not include your callsign or reason or similar in your modification. [thanks to HA5CQZ] - No need to insert anything like +4) Do not include your callsign or reason or similar in your modification, + just add the ideas behind to the commit message and/or the pull request. + Git will take care for recording it together with your authorship. + [thanks to HA5CQZ] + So there is no need to insert anything like **`// 2021-02-01 HA5SE implementing TUNE_LNG=`** Instead of comments like that, rather count on - **`git blame`** + **`git blame`** and/or **`git log`** 5) When defining global variables we have two choices: [thanks to DL1JBE] - * Variables which are only part of an module should be defined in the module itself - and made known to other modules by declaring them extern in the modules header file - * Alternatively if the variable is not clearly related to a functional module we have - concentrated them in one place - at the moment in **` main.c `** (with **` test/data.c `** a - shadow copy for testing purposes). The variable should then be declared in **` globalvars.h `** . + * Variables which are only part of an module should be defined in + the module itself and made known to other modules by declaring them + `extern` in the modules header file. + * Alternatively if the variable is not clearly related to a + functional module we have concentrated them in one place - at the + moment in **` main.c `** (with **` test/data.c `** a + shadow copy for testing purposes). + The variable should then be declared `extern` in **` globalvars.h `** .