[Home]

Summary:ASTERISK-26886: chan_pjsip: make PJSIP sample file point to wiki documentation a bit more explicitly
Reporter:xrobau (xrobau)Labels:
Date Opened:2017-03-20 15:50:17Date Closed:2017-03-30 15:44:13
Priority:MinorRegression?
Status:Closed/CompleteComponents:Documentation pjproject/pjsip
Versions:13.14.0 Frequency of
Occurrence		Constant
Related
Issues:
Environment:Attachments:
Description:As part of bug triage, we discovered that 'message_context' is a valid param to a pjsip endpoint, but it's not documented.

It was imported in https://reviewboard.asterisk.org/r/3384 in 12, but the pjsip example config file was not updated with it.

[edit by Rusty below]

I think we can make the pjsip.conf sample a little more helpful in pointing people to the areas of the wiki with pjsip documentation. We do provide more specific links in other parts of the sample file in regards to other configuration.

I'm going to open this up as a documentation issue for making the sample file point to appropriate documentation a bit more explicitly.
Comments:By: Asterisk Team (asteriskteam) 2017-03-20 15:50:18.276-0500

Thanks for creating a report! The issue has entered the triage process. That means the issue will wait in this status until a Bug Marshal has an opportunity to review the issue. Once the issue has been reviewed you will receive comments regarding the next steps towards resolution.

A good first step is for you to review the [Asterisk Issue Guidelines|https://wiki.asterisk.org/wiki/display/AST/Asterisk+Issue+Guidelines] if you haven't already. The guidelines detail what is expected from an Asterisk issue report.

Then, if you are submitting a patch, please review the [Patch Contribution Process|https://wiki.asterisk.org/wiki/display/AST/Patch+Contribution+Process].
By: Malcolm Davenport (mdavenport) 2017-03-20 16:25:32.874-0500

https://wiki.asterisk.org/wiki/display/AST/Asterisk+13+Configuration_res_pjsip#Asterisk13Configuration_res_pjsip-endpoint_message_context

no?
By: xrobau (xrobau) 2017-03-21 09:44:15.181-0500

I was looking here - https://github.com/asterisk/asterisk/blob/13/configs/samples/pjsip.conf.sample - as the wiki is hard to search, the place we look for configuration examples is in the actual configuration files themselves.

By: xrobau (xrobau) 2017-03-21 09:45:44.180-0500

I'm happy to be told 'don't do that, that's wrong', but I'm pretty sure it's not just us that do that 8)
By: Joshua C. Colp (jcolp) 2017-03-21 09:49:57.017-0500

The sample file isn't the definitive source. In fact:

{noformat}
; ============================================================================
; NOTICE NOTICE NOTICE NOTICE NOTICE NOTICE NOTICE NOTICE NOTICE NOTICE
;
; This file does not maintain the complete option documentation.
; ============================================================================
{noformat}
By: Joshua C. Colp (jcolp) 2017-03-21 09:51:46.051-0500

The documentation itself does have to exist when an option is added though, which guarantees the wiki is up to date as it is pulled from the source to produce the wiki.
By: Malcolm Davenport (mdavenport) 2017-03-21 09:55:57.996-0500

None of this stops someone from submitting a patch, because relevant patches are always welcome. But, I don't think we should put this task on the core team.

ye olde sip.conf got itself into a bit of a pickle because it was used as de facto documentation for using chan_sip.  We've been working against using the sample config files as documentation for a while (Josh's comment) as well as:

; It is not intended to teach PJSIP configuration or serve as an exhaustive
; reference of options and potential scenarios.
...
; The official documentation is at http://wiki.asterisk.org

and, I know you're not the only one, I see it also with users of res_digium_phone, and we work to point them back to the wiki.  The wiki isn't flawless, but it's a better place for consuming docs than the sample config file.
By: xrobau (xrobau) 2017-03-21 09:58:15.103-0500

Fair enough.

Can I suggest an expansion of that with adding a link TO the documentation then? It just vaguely links to wiki.asterisk.org, when it probably should be linking directly to https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+Configuration_res_pjsip or https://wiki.asterisk.org/wiki/display/AST/Asterisk+13+Configuration_res_pjsip

Feel free to close this ticket as 'Rob was wrong. Again'. (You have that as a jira resolution state, right? 8)



By: Malcolm Davenport (mdavenport) 2017-03-21 10:45:46.129-0500

Items that can be configured in pjsip.conf, in addition to what you linked, include documentation on the following wiki pages, just for 13:

https://wiki.asterisk.org/wiki/display/AST/Asterisk+13+Configuration_res_pjsip_acl
https://wiki.asterisk.org/wiki/display/AST/Asterisk+13+Configuration_res_pjsip_endpoint_identifier_ip
https://wiki.asterisk.org/wiki/display/AST/Asterisk+13+Configuration_res_pjsip_outbound_publish
https://wiki.asterisk.org/wiki/display/AST/Asterisk+13+Configuration_res_pjsip_outbound_registration
https://wiki.asterisk.org/wiki/display/AST/Asterisk+13+Configuration_res_pjsip_phoneprov_provider
https://wiki.asterisk.org/wiki/display/AST/Asterisk+13+Configuration_res_pjsip_publish_asterisk
https://wiki.asterisk.org/wiki/display/AST/Asterisk+13+Configuration_res_pjsip_pubsub

I think that's why the more generic pointer to wiki.asterisk.org is in there, rather than trying to tie the sample config file too directly to the full list of possibilities for pjsip.conf.
By: Rusty Newton (rnewton) 2017-03-23 09:23:49.605-0500

I think we can make the pjsip.conf sample a little more helpful in pointing people to the areas of the wiki with pjsip documentation. We do provide more specific links in other parts of the sample file in regards to other configuration.

I'm going to open this up as a documentation issue for making the sample file point to appropriate documentation a bit more explicitly.
By: Malcolm Davenport (mdavenport) 2017-03-30 15:44:08.320-0500

And I'm going to close this out because if we do this, it makes cherry-picking commits that affect config file samples not possible between versions.
By: Rusty Newton (rnewton) 2017-03-31 14:40:53.494-0500

I wasn't thinking we should link to version specific pages on the wiki. More that we should make it clear where people should be going or what they should be searching for. You can do that in a way that doesn't link to version specific content.

That being said, only so much time in the day and we've got plenty of other more important things to do. :D