chan_simpleusb, chan_usbradio: Add parameter to make scaling/clipping optional, fix issue #399

[davidgsd]

Add legacyaudioscaling parameter to allow scaling/clipping code to remain unchanged for existing installs or if user enables parameter in simpleusb/usbradio .conf. Summary of changes:

• Added a new "legacyaudioscaling" parameter to the configs/rpt/ simpleusb & usbradio .conf files (with default of yes for new installs), and to the samples/ .conf.sample files
• Set .legacyaudioscaling = 1 (default to true for existing installs that do not yet have the parm in the /etc/asterisk/ .conf files) in both channel drivers struct default initialization.
• Condition the areas of code that do scaling and clipping or rx and tx audio in both simpleusb_read() and usbradio_read() on o->legacyaudioscaling being true.
• Save the in the channel drivers store_config() functions.
• Add a print to _menu_print() in both channel drivers when showing other cfg settings to indicate that legacyaudioscaling is enabled.

Testing done:

• Ran code with SimpleUSB channel driver and no changes to simpleusb.conf and confirmed that legacyaudioscaling was enabled, and no audio or other issues resulted, ie. did several parrot tests. Confirmed the cfg was shown as set in susbtune utility print parameters option.
• Set legacyaudioscaling = no in simpleusb.conf, then repeated above tests and confirmed the parameter was not enabled.
• Ran code with USBRadio channel driver and no changes to usbradio.conf and confirmed that legacyaudioscaling was enabled, and no audio or other issues resulted, ie. did several parrot tests. Confirmed the cfg was shown as set in radiotune utility print parameters option.
• Set legacyaudioscaling = no in usbradio.conf, then repeated above tests and confirmed the parameter was not enabled.

Fixes issue #399.

[davidgsd]

(BTW if anyone knows why github is listing commits from last month that are unrelated to this PR or how I can prevent that I'd be interested to know. Github does show the correct file changes so that's not an issue and the PR should be good to go, but I have no idea why it's listing on this tab commits from previous PRs. I did of course sync my fork before any changes, and then created a new branch so it would not show any previous commits, and then did the PR from that branch.)

[InterLinked1]

(BTW if anyone knows why github is listing commits from last month that are unrelated to this PR or how I can prevent that I'd be interested to know. Github does show the correct file changes so that's not an issue and the PR should be good to go, but I have no idea why it's listing on this tab commits from previous PRs. I did of course sync my fork before any changes, and then created a new branch so it would not show any previous commits, and then did the PR from that branch.)

Are you cloning from the latest version of master before making your change on your branch and making a PR? In your fork, you may have to pull from "upstream" first. Maybe sync your fork before making any changes to ensure you're starting fresh.

If the merger makes sure to squash the changes I think it should be fine, but I'd really prefer there just be a single commit in PRs so we know everything's good to go. I can't even tell what the commit description would be the way it is now.

Also, for the commit name, it should be something like:

chan_simpleusb, chan_usbradio: Add parameter to make scaling/clipping optional

<brief description here>

Fixes #399

or something like that, to conform with the Asterisk commit message format: https://docs.asterisk.org/Development/Policies-and-Procedures/Commit-Messages/

[davidgsd]

Are you cloning from the latest version of master before making your change on your branch and making a PR? In your fork, you may have to pull from "upstream" first. Maybe sync your fork before making any changes to ensure you're starting fresh.

If the merger makes sure to squash the changes I think it should be fine, but I'd really prefer there just be a single commit in PRs so we know everything's good to go. I can't even tell what the commit description would be the way it is now.

Yes, I cloned from latest master, and before that sync'd my fork on github. Maybe I need to somehow squash/rebase my fork/branch before starting on a new PR? But that would seem contradictory to the point of a RCS.

Honestly, git is the most unintuitive software I have ever worked with in 30 years of being a software engineer. Would be great if Asterisk or ASL or anyone actually documented the full, complete and proper workflow (i.e. all git commands that need to be executed) to do a PR.

Just the fact that github says here that I "made 18 commits last month" and lists only a bunch of old files, yet then on the Files Changed tab shows none of those files and there shows the correct changes, is quite contradictory and would appear to be a bug in github itself.

Also, for the commit name, it should be something like:
...

Just updated that.

[Allan-N]

Yes, I cloned from latest master, and before that sync'd my fork on github.

Did you also sync your local copy? I will frequently use :

git stash
git pull --rebase
git stash pop

[davidgsd]

Yes, I cloned from latest master, and before that sync'd my fork on github.

Did you also sync your local copy? I will frequently use :

git stash
git pull --rebase
git stash pop

My process to do the PR was:

• sync my fork on github
• did a git pull in my working directory before starting any changes
• created a new branch in my working directory as suggested here: https://opensource.stackexchange.com/questions/6740/once-i-did-a-pr-on-a-repo-should-i-delete-my-fork though as is ususally the case with these git posts on stack exchange etc. there are many different answers and often conflicting information. But I did indeed do a git checkout -b clipfixpr with the idea being that when I then did the PR from that branch, only changes made on that branch would be listed.
• updated the code, did the git commit -a -m ..., the git push, and then did the PR on github on my clipfixpr branch.

From what you're suggesting, maybe the magic trick here is I need to add the --rebase when I do the git pull. What exactly that does is not clear to me from the git documentation, it is summarized as "Reapply commits on top of another base tip" which I have no idea why that would be needed in this process, or somewhere else it's described as "By default, a rebase will simply drop merge commits from the todo list, and put the rebased commits into a single, linear branch", which sounds nice, except that (as usual) there is no real world context provided as to when and why you would need to do that. If anyone can explain this more clearly why and when I should be doing that, it would be much appreciated. I'm sure git works great if you use it in exactly the right way, (though I have definitely seen some bugs in the github desktop app I use with another project, where our use cases are very simple) but it amazes me how none of these details ever seem to be documented anywhere for FOSS projects and it's like a secret unwritten sequence of spells that has to be hacked together one piece at a time. And to top it off, other guides say things like "As we've discussed previously in rewriting history, you should never rebase commits once they've been pushed to a public repository.".

[InterLinked1]

Are you cloning from the latest version of master before making your change on your branch and making a PR? In your fork, you may have to pull from "upstream" first. Maybe sync your fork before making any changes to ensure you're starting fresh.
If the merger makes sure to squash the changes I think it should be fine, but I'd really prefer there just be a single commit in PRs so we know everything's good to go. I can't even tell what the commit description would be the way it is now.

Yes, I cloned from latest master, and before that sync'd my fork on github. Maybe I need to somehow squash/rebase my fork/branch before starting on a new PR? But that would seem contradictory to the point of a RCS.

Honestly, git is the most unintuitive software I have ever worked with in 30 years of being a software engineer. Would be great if Asterisk or ASL or anyone actually documented the full, complete and proper workflow (i.e. all git commands that need to be executed) to do a PR.

It does take some time getting used to it, especially for less frequently performed operations.

Here is the Asterisk wiki page on it: https://docs.asterisk.org/Development/Policies-and-Procedures/Code-Contribution/

Some of that is not applicable to app_rpt since we don't have multiple branches and what not but a lot of it should be relevant.

You don't need the gh tool, you can ignore that and just use plain git.

[InterLinked1]

Yes, I cloned from latest master, and before that sync'd my fork on github.

Did you also sync your local copy? I will frequently use :

git stash
git pull --rebase
git stash pop

My process to do the PR was:

• sync my fork on github
• did a git pull in my working directory before starting any changes
• created a new branch in my working directory as suggested here: https://opensource.stackexchange.com/questions/6740/once-i-did-a-pr-on-a-repo-should-i-delete-my-fork (2nd answer). However, like all these git posts on stack exchange etc., there are a bunch of different answers and conflicting information. But anyhow I did indeed do a git checkout -b clipfixpr with the idea being that when I then did the PR from that branch, only changes made on that branch would be listed.
• updated the code, did the git commit -a -m ..., the git push, and then did the PR on github on my clipfixpr branch.

From what you're suggesting, maybe the magic trick here is I need to add the --rebase when I do the git pull. What exactly that does is not clear to me from the git documentation, it is summarized as "Reapply commits on top of another base tip" which I have no idea why that would be needed in this process, or somewhere else it's described as "By default, a rebase will simply drop merge commits from the todo list, and put the rebased commits into a single, linear branch", which sounds nice, except that (as usual) there is no real world context provided as to when and why you would need to do that. If anyone can explain this more clearly why and when I should be doing that, it would be much appreciated. I'm sure git works great if you use it in exactly the right way, (though I have definitely seen some bugs in the github desktop app I use with another project, where our use cases are very simple) but it amazes me how none of these details ever seem to be documented anywhere for FOSS projects and it's like a secret unwritten sequence of spells that has to be hacked together one piece at a time. And to top it off, other guides say things like "As we've discussed previously in rewriting history, you should never rebase commits once they've been pushed to a public repository.".

So, a rebase is normally required when a lot of time has passed since a change was written. I used to have to do this a lot with the Asterisk repo back when it was on Gerrit. If you make a change at a particular time, your commit is a diff against a particular commit. As time passes, other commits may get merged into the branch on which you originally made your commit, but your branch doesn't have those changes. A rebase effectively pulls in all those changes and "rebases" your commit on top of the current HEAD so those changes are in the branch, and your commit is against a newer version of the branch, effectively.

Took me some time to internally intuit that but once you've seen it happen it makes more sense. I don't have to rebase often myself, usually only when there's some kind of conflict that necessitates one or when asked.

[davidgsd]

Just pushed with updates for all above review comments. (I did also try Allan's suggestion of the git stash, git pull --rebase, git stash pop, but it seemed to have no effect, the PR still shows only a bunch of old files on this tab and only the correct new changes on the Files Changed tab.)

[davidgsd]

Here is the Asterisk wiki page on it: https://docs.asterisk.org/Development/Policies-and-Procedures/Code-Contribution/
Some of that is not applicable to app_rpt since we don't have multiple branches and what not but a lot of it should be relevant.
You don't need the gh tool, you can ignore that and just use plain git.

Unfortunately the above wiki page seems very specific to Asterisk, uses yet another tool (gh) adding even more complexity, and like all these guides doesn't explain why each step is needed. It's just a long list of random commands and as soon as what you're doing in a specific context is a little bit different the whole guide becomes essentially useless. I've read books on git. I get the overall idea of what's it's doing. I even have a minor in math, and like graph theory, topology and that sort of stuff. But while git seems nice in theory the real-world implementation seems to be way more complicated than it should be.

It occurred to me this is somewhat analogous to proper state machine design in embedded systems development. To create reliable, deterministic embedded software you often have to enumerate the possible states of a process and define all the actions that have to take place during all possible state transitions. The software configuration management process is very similar. There are states and transitions such as fork repo, sync fork, create branch, push changes, create PR, merge PR, that should be easy to enumerate. And for each such state transition there are very specific git commands that should be used, or weird things happen and various 'hacks' may then be required. Does anyone really fundamentally understand what all these commands are for the context of app_rpt and why they're needed, or do these bits and pieces just get hacked together pragmatically as needed?

I see the above guide recommends doing:

    git checkout master
    git pull upstream master
    git push

after the git clone, and it'd be nice if they would explain why. In past development on other projects a git clone was always sufficient to get what you'd think would in fact be a clone of the master repo, and I've previously not needed to do additional checkouts, pulls and pushes before being able to do anything else.

[davidgsd]

After more web searches I think I am starting to find some better guides on the PR process with git:
https://github.com/susam/gitpr (very detailed)
https://gist.github.com/james-priest/74188772ef2a6f8d7132d0b9dc065f9c
https://gist.github.com/Chaser324/ce0505fbed06b947d962
Lots of reading to do...

[davidgsd]

Pushed requested whitespace cleanups. And also tried a few suggestions from the above 3 guides, but they all seemed to do absolutely nothing. I tried all the following, with the idea that maybe it would somehow sync up my directory to the main upstream repo and those old commits showing on this tab might go away, but as usual with git things don't seem to work very predictably.
2043 git remote add upstream [email protected]:AllStarLink/app_rpt.git
2044 git remote -v
2045 git pull upstream master
2046 git diff
2047 git checkout master
2048 git stash
2049 git checkout master
2050 git pull upstream master
2051 git push origin master
2052 git checkout clipfixpr
2053 git diff
2054 git stash pop
2055 git diff
2056 git stash
2057 git checkout master
2058 git rebase master
2059 git fetch upstream
2060 git branch -va
2061 git checkout master
2062 git merge upstream/master
2063 git checkout clipfixpr
2064 git diff
2065 git stash pop
2066 git diff
2067 git commit -a -m "whitespace cleanups"
2068 git fetch upstream
2069 git checkout master
2070 git merge upstream/master
2071 git checkout clipfixpr
2072 git diff
2073 git rebase master
2074 git checkout
2075 git rebase -i master
2076 git diff
2077 git checkout clipfixpr
2078 git status
2079 git push

It never ceases to amaze how there are 1,000's of guides, posts, books, etc. on git, with 100's of different commands and 1,000's of differenct combinations/permutations, but they rarely seem to actually do anything.

[InterLinked1]

Here is the Asterisk wiki page on it: https://docs.asterisk.org/Development/Policies-and-Procedures/Code-Contribution/
Some of that is not applicable to app_rpt since we don't have multiple branches and what not but a lot of it should be relevant.
You don't need the gh tool, you can ignore that and just use plain git.

Unfortunately the above wiki page seems very specific to Asterisk, uses yet another tool (gh) adding even more complexity,

As I said, you don't need the gh tool, it's optional. I'm an Asterisk contributor and I've never used the gh tool.

and like all these guides doesn't explain why each step is needed. It's just a long list of random commands and as soon as what you're doing in a specific context is a little bit different the whole guide becomes essentially useless. I've read books on git. I get the overall idea of what's it's doing. I even have a minor in math, and like graph theory, topology and that sort of stuff. But while git seems nice in theory the real-world implementation seems to be way more complicated than it should be.

It occurred to me this is somewhat analogous to proper state machine design in embedded systems development. To create reliable, deterministic embedded software you often have to enumerate the possible states of a process and define all the actions that have to take place during all possible state transitions. The software configuration management process is very similar. There are states and transitions such as fork repo, sync fork, create branch, push changes, create PR, merge PR, that should be easy to enumerate. And for each such state transition there are very specific git commands that should be used, or weird things happen and various 'hacks' may then be required. Does anyone really fundamentally understand what all these commands are for the context of app_rpt and why they're needed, or do these bits and pieces just get hacked together pragmatically as needed?

I see the above guide recommends doing:

    git checkout master
    git pull upstream master
    git push

after the git clone, and it'd be nice if they would explain why. In past development on other projects a git clone was always sufficient to get what you'd think would in fact be a clone of the master repo, and I've previously not needed to do additional checkouts, pulls and pushes before being able to do anything else.

A git clone is sufficient the instant you clone it, but repos are often cloned once and then used for a long period of time. Whenever I'm working on stuff in my local asterisk fork for example, I do indeed do a git pull upstream master (or git pull origin master, if I know my origin is also up to date with upstream). I think that's the reason it's included there, you would run one of those two commands (but not both).

I certainly hear what you're saying... it's taken me years of using git on a regular basis (weekly, if not daily) to feel fairly comfortable with it, but if I'm doing something rather out of the ordinary, then I still need to look up the right procedure.

[davidgsd]

This link has a pretty good summary of the PR workflow, https://blog.scottlowe.org/2015/01/27/using-fork-branch-git-workflow and suggests:

1. Fork a GitHub repository.
2. Clone the forked repository to your local system.
3. Add a Git remote for the original repository.
4. Create a feature branch in which to place your changes.
5. Make your changes to the new branch.
6. Commit the changes to the branch.
7. Push the branch to GitHub.
8. Open a pull request from the new branch to the original repo.
9. Clean up after your pull request is merged.

Looks like I skipped (3) so maybe that's why old commits are listed on this page.