Documentation issueshttps://lab.civicrm.org/groups/documentation/-/issues2022-10-11T15:38:06Zhttps://lab.civicrm.org/documentation/docs/dev/-/issues/436Resolve duplicate content on API interfaces2022-10-11T15:38:06ZhomotechsualResolve duplicate content on API interfaces*Created by: seancolsen*
Duplicate content here:
* REST
* https://docs.civicrm.org/dev/en/latest/api/usage/#rest
* https://docs.civicrm.org/dev/en/latest/api/interfaces/#rest
* AJAX
* https://docs.civicrm.org/dev/en/latest...*Created by: seancolsen*
Duplicate content here:
* REST
* https://docs.civicrm.org/dev/en/latest/api/usage/#rest
* https://docs.civicrm.org/dev/en/latest/api/interfaces/#rest
* AJAX
* https://docs.civicrm.org/dev/en/latest/api/interfaces/#ajax
* https://docs.civicrm.org/dev/en/latest/api/usage/#ajax
And other sections in those two pages "smarty" etc...
I think the "Interfaces" page is probably the better place for this content. We should move content out of the "Usage" page and into the "Interfaces" page in order to resolve this duplication.https://lab.civicrm.org/documentation/docs/dev/-/issues/446No decent google search results for "civicrm submit patch" or "civicrm pull r...2022-10-11T15:37:47ZMichael McAndrewNo decent google search results for "civicrm submit patch" or "civicrm pull request""civicrm submit patch" and "civicrm pull request" area phrases that I instinctively google when looking for instructions on how to submit a patch.
The documentation does cover the basics in https://docs.civicrm.org/dev/en/latest/core/co..."civicrm submit patch" and "civicrm pull request" area phrases that I instinctively google when looking for instructions on how to submit a patch.
The documentation does cover the basics in https://docs.civicrm.org/dev/en/latest/core/contributing/#make-changes and https://docs.civicrm.org/dev/en/latest/tools/git/#pr-submit but these are h2 and h3s.
But it is too buried.
IMO something like "Your first pull request", "Creating a pull request" "Pull Request guidelines" or similar should be the first result in google and it should take you to a page entitled "Creating a pull request" or similar (not Git, GitHub, and GitLab or How to contribute, both of which are too vague).
I know it is complicated, and we want to encourage high quality PRs and commits, etc. but I think that we need to refactor some content in the above two pages. Am willing to have a stab at that. Wanted to get opinions first...https://lab.civicrm.org/documentation/docs/dev/-/issues/456Improved intro / quickstart documentation for testing2022-10-11T15:37:29ZMichael McAndrewImproved intro / quickstart documentation for testingThe testing documentation starts off with writing tests. It doesn't cover running tests until half way down this second tier page: https://docs.civicrm.org/dev/en/latest/testing/phpunit/.
Arguably, people will want to make sure they hav...The testing documentation starts off with writing tests. It doesn't cover running tests until half way down this second tier page: https://docs.civicrm.org/dev/en/latest/testing/phpunit/.
Arguably, people will want to make sure they have been able to run the test suite before thinking about writing a test, and I think we should try and find a way make running tests much more visible.
This is a similar issue to https://github.com/civicrm/civicrm-dev-docs/issues/446 (which I am yet to get around to implementing :blush:) but I wanted to report it in any case.
One solution would be to have 'Running tests' and 'Writing tests' as two main headings on the testing page (in that order). Each of these sections would give a brief intro and point towards the details contained in other testing pages.
Thoughts?https://lab.civicrm.org/documentation/docs/dev/-/issues/713Improve install docs to remove this impass2022-10-11T15:31:08ZhomotechsualImprove install docs to remove this impass*Created by: eileenmcnaughton*
https://github.com/totten/civix/pull/166
- the issue gives info as to what is needed*Created by: eileenmcnaughton*
https://github.com/totten/civix/pull/166
- the issue gives info as to what is neededhomotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs/dev/-/issues/458What tests does Jenkins run?2022-10-11T15:28:41ZMichael McAndrewWhat tests does Jenkins run?https://docs.civicrm.org/dev/en/latest/testing/continuous-integration/ says "Unfortunately, the full test suite would take several hours longer, so Jenkins only runs some tests at this stage."
I'm wondering what tests Jenkins runs, and ...https://docs.civicrm.org/dev/en/latest/testing/continuous-integration/ says "Unfortunately, the full test suite would take several hours longer, so Jenkins only runs some tests at this stage."
I'm wondering what tests Jenkins runs, and if these are publicly documented somewhere that we can reference for those that are interested. Especially if the actual tests that we run are liable to change a fair amount (and we risk the documentation getting out of date).https://lab.civicrm.org/documentation/docs/dev/-/issues/459Are we keeping track of page not found errors?2022-10-11T15:28:32ZMichael McAndrewAre we keeping track of page not found errors?It would be good to log these so we can create missing redirects if and when necessary.It would be good to log these so we can create missing redirects if and when necessary.https://lab.civicrm.org/documentation/docs/dev/-/issues/465Should we update the Region Reference docs? Or delete them?2022-10-11T15:28:24ZhomotechsualShould we update the Region Reference docs? Or delete them?*Created by: seancolsen*
I'd like some feedback from others on how we should be aiming to document CiviCRM's regions.
## The current situation
1. We have a [Region Reference](https://docs.civicrm.org/dev/en/latest/framework/region/) ...*Created by: seancolsen*
I'd like some feedback from others on how we should be aiming to document CiviCRM's regions.
## The current situation
1. We have a [Region Reference](https://docs.civicrm.org/dev/en/latest/framework/region/) page with a bunch of good content about how regions work and how to use them.
* There's also a [section within that page which lists _specific regions_](https://docs.civicrm.org/dev/en/latest/framework/region/). That's what I'm talking about here.
* That list of regions [came over from the wiki](https://github.com/civicrm/civicrm-dev-docs/commit/a6b5e487e6f77103c1e0e7dd2855d4aaf60292e2) where it appears to [have been authored](https://wiki.civicrm.org/confluence/pages/viewpreviousversions.action?pageId=86213455) mostly by @totten and @eileenmcnaughton
* In theory, I like the idea of maintaining a list of regions in the docs, but only if it's a _complete_ list and if adds value beyond what a developer would find by grepping `templates` for `{crmRegion`.
* Currently the list is incomplete. I can help complete it, but I'm not actually convinced it's worth it for us to maintain this.
1. In https://github.com/civicrm/civicrm-core/pull/11439 @tunbola added a new region a couple days ago.
1. @colemanw merged this PR even though it lacked corresponding documentation. (Normally the missing doc would bother me, but in this case I'm kind of on the fence about whether it even should be documented.)
1. Later, @tunbola reached out to me to ask where to add the appropriate docs, given that there is no "Contact" section in the list of regions. It really had me scratching my head.
## Options for moving forward
* Flesh out the "List of Regions" documentation to mention the missing regions, including the newly added `contact-page-inline-actions` region.
* **Or**... Remove the list of specific regions altogether and replace it with generic instructions for finding regions by inspecting the codebase.
## Finding undocumented regions
Just in case we do decide to keep the list, here's how we can make it complete. This bash snippet compares the codebase to the docs to spot missing regions.
```bash
civicrmDir="$HOME/buildkit/build/dmaster/sites/all/modules/civicrm"
devGuideDir="$HOME/civicrm/documentation/guides/dev"
regions=$(grep -Phiro '\{crmRegion((?!\}).)*\}' "$civicrmDir/templates" \
| grep -Po '(?<=name=)((?!\s|\}).)*' \
| sed -E 's/("|'"'"')//g' \
| sort | uniq)
while read -r region; do
if ! grep -q "$region" "$devGuideDir/docs/framework/region.md" ; then
echo $region
fi
done <<< "$regions"
```
Currently this gives:
```text
billing-block-post
billing-block-pre
case-activity-form
contact-addresses
contact-basic-info-left
contact-basic-info-right
contact-comm-pref
contact-demographic
contact-details-left
contact-details-right
contact-page-inline-actions
contribute-form-contributionpage-addproduct-main
contribution-soft-credit-block
crm-activity-userdashboard-post
custom-data-view-`$cd_edit.name`
$customRegion
onbehalf-block
payment-edit-block
payment-info-block
profile-form-`$ufGroupName`
profile-search-`$ufGroupName`
profile-view-`$ufGroupName`
$region
```
Some of those are actually already documented, like `contribute-form-contributionpage-addproduct-main` which is misspelled in the docs, or ``profile-form-`$ufGroupName``` which is documented as `profile-form-(NAME)`. But most of that list above represents missing doc.https://lab.civicrm.org/documentation/docs/dev/-/issues/470Document how to contribute by doing triage2022-10-11T15:28:02ZhomotechsualDocument how to contribute by doing triage*Created by: eileenmcnaughton*
@ErikHommel has offered to help up with doing triage. I think that since this is a task community members take on a times to contribute we should document it. Here is my take:
Triage is doing one or more ...*Created by: eileenmcnaughton*
@ErikHommel has offered to help up with doing triage. I think that since this is a task community members take on a times to contribute we should document it. Here is my take:
Triage is doing one or more of the following actions, either to issues you logged or just randomly from the list below. Ideally we would co-opt 2-3 people to spend an hour or 2 a week on triage.
The first priority with triage is to ensure incoming issues [Incoming issues](https://issues.civicrm.org/jira/issues/?filter=32110&jql=project%20in%20(CRM%2C%20INFRA)%20AND%20resolution%20%3D%20Unresolved%20AND%20created%20%3E%3D%20-7d%20ORDER%20BY%20priority%2C%20key) are triaged
1. determine if it is accurately categorised as bug vs improvement
2. detemine if priority is appropriate
3. try to ensure component description & title are correct & meaningful
3. determine if the issue still is replicable on the latest master
4. ask any additional questions that seem necessary
5. provide any first-level support you feel able to.
6. announce any new regressions or critical issues (that really are) on the product-maintenance channel in chat
7. discuss any that are hard to triage on the product-maintenance channel in chat
This is a [good example](https://issues.civicrm.org/jira/browse/CRM-20711) of a triager doing the above steps -
Prioritisaion can be tricky. I consider
**'Blocker'** to be only applicable to something that would block the next release going out or change the release schedule to get a new hot fix out.
**Critical** is something that - causes data integrity errors or a fatal error or for CiviCRM to do something substantially different to what it 'says it will do' - e.g the group of people who receive an email being different from those selected.
**Important** is generally for subsytems IMHO - ie. something that would be a blocker or critical for work that is not currently part of our core offering - such as Drupal 8, Mosaico, new CiviCase
**Major** includes things that have an notable impact on many users or significant impact on a smaller set.
**Minor** is a significant impact in an obscure scenario or a minor impact or an important improvement request.
**Trivial** is ... trivial - e.g wording, translation (sorry people). most improvement requests
Where an issue has been logged or championed by someone who could fix it themselves (e.g a partner) but has not I think that is an indication to err on the side of lowering the priority or considering it to be an 'Improvement request' rather than a bug. Ditto where a bug is newly discovered but has been around for a long time. For example if a behaviour has been in place since 4.5 then it would be hard to make a case for it to be a major bug.https://lab.civicrm.org/documentation/docs/dev/-/issues/476Document 'custom data on any entity'2022-10-11T15:27:47ZhomotechsualDocument 'custom data on any entity'*Created by: eileenmcnaughton*
@MegaphoneJon place holder for the upcoming ability to have custom data against other entities*Created by: eileenmcnaughton*
@MegaphoneJon place holder for the upcoming ability to have custom data against other entitieshttps://lab.civicrm.org/documentation/docs/dev/-/issues/486Improve discoverability of internal URL standards2022-10-11T15:27:40ZhomotechsualImprove discoverability of internal URL standards*Created by: seancolsen*
As @GinkgoFJG describes [here](https://github.com/civicrm/civicrm-user-guide/pull/250#issuecomment-368461465)
> For what it's worth, the internal URL standards link is not easily discoverable for new (newish?)...*Created by: seancolsen*
As @GinkgoFJG describes [here](https://github.com/civicrm/civicrm-user-guide/pull/250#issuecomment-368461465)
> For what it's worth, the internal URL standards link is not easily discoverable for new (newish?) contributors. From the [main GitHub page for the user guide](https://github.com/civicrm/civicrm-user-guide), I followed the link under the "Contributing to this guide" header to the [Contributing to this guide page](https://docs.civicrm.org/user/en/latest/the-civicrm-community/contributing-to-this-manual/) and then the [Documentation style guide](https://docs.civicrm.org/dev/en/latest/documentation/style-guide/), which has several headings relating to URLs, but none of which answered my question. I don't remember whether or not it occurred to me to look in the left menu for related content in the same chapter, but I'm sure I wouldn't have thought to look in the chapter named Markdown.
Do address this issue, we should probably make some improvements to the Dev Guide as well as to other guides.https://lab.civicrm.org/documentation/docs/dev/-/issues/492Refer to GitLab instead of Jira, where appropriate2022-10-11T15:27:33ZhomotechsualRefer to GitLab instead of Jira, where appropriate*Created by: seancolsen*
The Dev Guide makes a lot of references to Jira. This command will find a few dozen of them (while ignoring URLs to specific Jira tickets)...
```
$ grep -Prin 'jira(?!/browse)' docs
```
There are some tricky q...*Created by: seancolsen*
The Dev Guide makes a lot of references to Jira. This command will find a few dozen of them (while ignoring URLs to specific Jira tickets)...
```
$ grep -Prin 'jira(?!/browse)' docs
```
There are some tricky questions to answer here, like what to we write in our [commit messages](https://docs.civicrm.org/dev/en/latest/tools/git/#commit-messages)?
Any interest from @bgm @totten @colemanw in helping with this task of updating the Dev Guide (since there are some decisions involved here)?https://lab.civicrm.org/documentation/docs/dev/-/issues/498Fix a few broken links / references2022-10-11T15:27:21ZxurizaemonFix a few broken links / referenceshttps://lab.civicrm.org/documentation/docs/dev/-/issues/500Pull developer documentation on tokens out of CiviMail2022-10-11T15:27:15ZMichael McAndrewPull developer documentation on tokens out of CiviMailThe token reference is currently found here: https://docs.civicrm.org/dev/en/latest/framework/civimail/#tokens
This might have made sense a while ago, but tokens are now more that just a CiviMail thing. They are like a mail merge functi...The token reference is currently found here: https://docs.civicrm.org/dev/en/latest/framework/civimail/#tokens
This might have made sense a while ago, but tokens are now more that just a CiviMail thing. They are like a mail merge functionality (not quite a templating language, I guess, but almost) that has applications (current and potential) in other parts of the system. e.g. I am using them in [chatbot](https://github.com/3sd/civicrm-chatbot).
It would be good to create https://docs.civicrm.org/dev/en/latest/framework/tokens and have them live there.https://lab.civicrm.org/documentation/docs/dev/-/issues/501Reference Flexmailer in CiviMail documentation2022-10-11T15:27:06ZMichael McAndrewReference Flexmailer in CiviMail documentation"FlexMailer (org.civicrm.flexmailer) is an email delivery engine for CiviCRM v4.7+. It replaces the internal guts of CiviMail. It is a drop-in replacement which enables other extensions to provide richer email features."
Flexmailer has ..."FlexMailer (org.civicrm.flexmailer) is an email delivery engine for CiviCRM v4.7+. It replaces the internal guts of CiviMail. It is a drop-in replacement which enables other extensions to provide richer email features."
Flexmailer has fairly comprehensive documentation here: https://docs.civicrm.org/flexmailer/en/latest/ but it is not mentioned in https://docs.civicrm.org/dev/en/latest/framework/civimail.
Given that Flexmailer is designed to be the future of mail in CiviCRM, and the place where developers should be focusing their efforts (rather than hacking CiviMail) we should reference the flexmailer documentation in https://docs.civicrm.org/dev/en/latest/framework/civimail and let people know that they should focus their efforts there.https://lab.civicrm.org/documentation/docs/dev/-/issues/519Re-write "Check the Fix Version" step of "Verify a bug fix" for compatibility...2022-10-11T15:26:45ZhomotechsualRe-write "Check the Fix Version" step of "Verify a bug fix" for compatibility with GitLab tickets*Created by: seancolsen*
This content is Jira-specific:
https://docs.civicrm.org/dev/en/latest/core/verify-fix/#step-1-check-the-fix-version-in-jira
What should people actually be doing in this step if the ticket is a GitLab ticket?
...*Created by: seancolsen*
This content is Jira-specific:
https://docs.civicrm.org/dev/en/latest/core/verify-fix/#step-1-check-the-fix-version-in-jira
What should people actually be doing in this step if the ticket is a GitLab ticket?
@mlutfy @totten any recommendations?https://lab.civicrm.org/documentation/docs/dev/-/issues/534Document the Form Array standard2022-10-11T15:26:35ZhomotechsualDocument the Form Array standard*Created by: eileenmcnaughton*
Per https://lab.civicrm.org/dev/core/issues/115 we have a new standard for defining form fields at the php level & such that they can be generically displayed & overridden via php (e.g in the buildForm hoo...*Created by: eileenmcnaughton*
Per https://lab.civicrm.org/dev/core/issues/115 we have a new standard for defining form fields at the php level & such that they can be generically displayed & overridden via php (e.g in the buildForm hook) by changing what fields are assigned
The specification is for an iterable fields array that would be assigned as
$this->assign('entityFields', $fields); or similar - e.g[ per this pr](https://github.com/civicrm/civicrm-core/pull/12078/files#diff-e0aa42922a99e97c7373924289bc0bf6R259) or the [entity trait](https://github.com/civicrm/civicrm-core/blob/master/CRM/Core/Form/EntityFormTrait.php#L88)
And the tpl level it is rendered through & iterated - e.g per [FIeld.tpl](https://github.com/civicrm/civicrm-core/blob/master/templates/CRM/Core/Form/Field.tpl)
Field spec (first cut) looks like
'field_1' => [
'name' => 'field_1',
'description' => ts("description to show below field"),
'help' => ['id' => 'id-field_1, 'file' => 'CRM/Contact/Form/Contact',
'is_add_translate_dialog' => 1,
],
'field_1' => ['name' => 'field_1'],
'money_field' => ['name' => 'money', 'formatter' => 'crmMoney'],
'weird_looking_field' => [
'name' => 'weird_looking_field',
'template' => CRM/Member/Form/MembershipType/weird_looking_field.tpl',https://lab.civicrm.org/documentation/docs/dev/-/issues/553How to do permission checks in angular2022-10-11T15:26:25ZhomotechsualHow to do permission checks in angular*Created by: eileenmcnaughton*
Just making some notes on something I just learnt - to check for permissions in an angular page in an extension
1) in the foo.ang.php file add
```
\Civi::resources()->addPermissions(['edit all contacts'])...*Created by: eileenmcnaughton*
Just making some notes on something I just learnt - to check for permissions in an angular page in an extension
1) in the foo.ang.php file add
```
\Civi::resources()->addPermissions(['edit all contacts']);
```
2) in the foo.js file add
```
$scope.checkPerm = CRM.checkPerm;
```
3) this can then be used in your angular html -eg
```
<p ng-if="checkPerm('edit all contacts')"> you are all powerful and can wreak havoc </p>
```https://lab.civicrm.org/documentation/docs/dev/-/issues/624Document url param support in search2022-10-11T15:25:41ZhomotechsualDocument url param support in search*Created by: eileenmcnaughton*
We have been increasingly standardising our approach to fields in the search form. Fields that have been standardised can be passed in via the url - this is a bit of a moving target.
The format for dates ...*Created by: eileenmcnaughton*
We have been increasingly standardising our approach to fields in the search form. Fields that have been standardised can be passed in via the url - this is a bit of a moving target.
The format for dates is
fieldname_high=YmdHis - eg
contribution_cancel_date_high=20180101150000
for 3 pm on 1 Jan 2018
Incomplete list of fields that work: (or will when https://github.com/civicrm/civicrm-core/pull/14594 is merged)
Contribution search & possibly advanced search
receive_date
contribution_cancel_date
invoice_number
Note that url support includes relative dates see
https://github.com/civicrm/civicrm-core/pull/14893https://lab.civicrm.org/documentation/docs/dev/-/issues/632Document new dedupe end points2022-10-11T15:25:31ZhomotechsualDocument new dedupe end points*Created by: eileenmcnaughton*
https://github.com/civicrm/civicrm-core/pull/14394*Created by: eileenmcnaughton*
https://github.com/civicrm/civicrm-core/pull/14394https://lab.civicrm.org/documentation/docs/dev/-/issues/647Document how permissions should be implemented for new DAO2022-10-11T15:24:16ZhomotechsualDocument how permissions should be implemented for new DAO*Created by: eileenmcnaughton*
@colemanw built a pretty clever structure whereby the permissions / ACL structure is pretty extendable but I don't think it's documented. @colemanw I'm making a start - can you flesh out
As I understand i...*Created by: eileenmcnaughton*
@colemanw built a pretty clever structure whereby the permissions / ACL structure is pretty extendable but I don't think it's documented. @colemanw I'm making a start - can you flesh out
As I understand it
- basic_get
- apiv3 (to some extent)
- apiv4
- civi reports (to some extent)
- build in search (very patchy)
All implement ACLs based on calling the relevant BAO/DAO's addSelectWhereClause if
1) check_permissions is true (e.g per setting in an API call, or always in search)
2) it exists (otherwise fall back it to the Core_DAO one)
This is called from basic_get & from reports that call buildPermissions (extended reports now does this, sketchy in core)
And generally implements a hook per BAO/DAO