harukin/core
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Integrated more content and deleted the original locations where applicable.

Browse Source
This commit is contained in:
Andrew Manning 2017-02-13 20:37:58 -05:00
parent a3436aea02
commit 05fd5eb8be
13 changed files with 181 additions and 839 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
doc/admin/administrator_guide.md
View File

@ -245,6 +245,21 @@ have a different techlevel than a community for Linux kernel developers.
This role is not supported by the hubzilla community. This role is not supported by the hubzilla community.
### Techlevels
Techlevels is a unique feature of Hubzilla 'pro'. It is not available in other server_roles, although it expands on the concepts introduced in $Projectname 'basic'.
We've implemented several different mechanisms in order to reduce the apparent complexity and learning curve presented to new members. At the same time, we do not wish to limit any functionality for people who are able to grasp some slightly advanced technical technical features. The first mechanism was to move several features to an optional 'Features' page where they could be enabled at will; with the default interface kept somewhat lean.
The problem we had now is that the number of features began to grow dramatically, and the Feature page is daunting in possibilities. There are also features present which probably should not be available to all members, but may be extremely useful to those with technical backgrounds.
The techlevels seeeks to remedy this by grouping features within different levels of technical ability; starting at 0 (uncomfortable with technology), and up to 5 (Unix wizard or equivalent).
When a new member registers, their account is provided a techlevel setting of 0. On the account settings page they may change this to any available level. A higher level opens more advanced features and possible interactions.
The account administrator may also lock a particular level, lock a maximum level, or change/re-arrange the features available to any level. Those with the minimum level are typically not very exploratory and are unlikely to discover the advanced modes. This is by design. Those that look around and desire more interactions will find them. In the absence of administrator defaults they may choose any level. As they look at the features available to the level in question, it is generally expected that they will discover some features are beyond their comprehension and it is hoped they will back off to a level where the interface and features are comfortable to their skill level. This is somewhat experimental at present and for that reason is not part of the 'standard' server role. The standard server role is preset to level '5', and the basic server role is preset to level '0', with no possibility of change. Members in these roles may find themselves overwhelmed or underwhelmed by the feature set and complexity.
### Service Classes ### Service Classes
Service classes allow you to set limits on system resources by limiting what individual Service classes allow you to set limits on system resources by limiting what individual

4
doc/database.bb
View File

@ -1,6 +1,4 @@
[h2]Database Tables[/h2] [h2]Database Tables[/h2][table border=1][tr][th]Table[/th][th]Description[/th][/tr]
[table]
[tr][th]Table[/th][th]Description[/th][/tr]
[tr][td][zrl=[baseurl]/help/database/db_abconfig]abconfig[/zrl][/td][td]arbitrary storage for connections of local channels[/td][/tr] [tr][td][zrl=[baseurl]/help/database/db_abconfig]abconfig[/zrl][/td][td]arbitrary storage for connections of local channels[/td][/tr]
[tr][td][zrl=[baseurl]/help/database/db_abook]abook[/zrl][/td][td]connections of local channels[/td][/tr] [tr][td][zrl=[baseurl]/help/database/db_abook]abook[/zrl][/td][td]connections of local channels[/td][/tr]
[tr][td][zrl=[baseurl]/help/database/db_account]account[/zrl][/td][td]service provider account[/td][/tr] [tr][td][zrl=[baseurl]/help/database/db_account]account[/zrl][/td][td]service provider account[/td][/tr]

2
doc/developer/covenant.bb
View File

@ -43,5 +43,5 @@ Project maintainers who do not follow or enforce the Code of Conduct in good fai
[h3]Attribution[/h3] [h3]Attribution[/h3]
This Code of Conduct is adapted from the [url="http://contributor-covenant.org"]Contributor Covenant[/url], version 1.4, available at [url="http://contributor-covenant.org/version/1/4/"]http://contributor-covenant.org/version/1/4[/url]. This Code of Conduct is adapted from the [url=http://contributor-covenant.org]Contributor Covenant[/url], version 1.4, available at [url=http://contributor-covenant.org/version/1/4/]http://contributor-covenant.org/version/1/4[/url].

386
doc/developer/developer_guide.bb
View File

@ -13,23 +13,43 @@ We're pretty relaxed when it comes to developers. We don't have a lot of rules.
This document will help you get started learning and contributing to $Projectname. This document will help you get started learning and contributing to $Projectname.
[h3]Versioning system[/h3] [h3]Versions and Releases[/h3]
The versioning system is similar to the popular semantic versioning but less stringent. Given x.y.z, x changes yearly. y changes for "stable" monthly builds, and z increments when there are interface changes. We maintain our date and build numbers for medium grain version control (commits within a certain date range) and of course git revs for fine grained control. $Projectname currently uses a standard version numbering sequence of $x.$y(.$z), for instance '1.12' or '1.12.1'. The first digit is the major version number. Major versions are released "roughly" once per year; often in December.
The second digit is the minor release number. If this number is odd, it is a development version. If the number is even, it is a released version. Minor versions are released (moved from dev to master) typically once per month when development is 'stable', but this is likely to increase. Going forward minor releases will be made somewhere between one and three months; corresponding to a stable code point and when there is general community consensus that the current code base is stable enough to consider a release.
The final digit is an interface or patch designator.
The release process involves changing the version number (by definition the minor version number will be odd, and the minor number will be incremented). Once a year for a major release the major version will be incremented, and the minor number reset to 0.
The release candidate is moved to a new branch; and testing will commence/continue for a period of 1-2 weeks afterward or until any significant issues have been resolved. This branch is usually labelled with RC (release candidate); for instance 1.8RC represents the pending release of version 1.8. At this time, the minor version number on the dev branch is incremented to the next odd number. (For instance 1.9). New development can then take place in the dev branch.
Bug fixes should always be applied to 'dev' and from there merged forward (typically with git cherry-pick) to the RC branch and if necessary applied to the master or official release branch.
At the time a release candidate is produced, the language strings file is frozen until a release is made. Translation work may continue, but all translations should be submitted to 'dev' and merged forward to RC.
Once RC testing is completed, RC is merged to 'master' and the RC version designator removed; resulting in one final checkin to change the version number. The CHANGELOG file should also be updated at or just prior to this time. If there are merge conflicts during this final merge, the merge will be abandoned; and 'git merge -s ours' applied. This results in a replacement of master with the contents of the RC branch. Conflicts often arise with string updates which were made to master after the last release and cannot easily be resolved without hand editing. Since this is a release of tested code, hand editing is discouraged, and the replacement merge strategy should be used instead. It is assumed that RC now contains the most recent well-tested code.
Once the release is live and merged to master, the RC branch may be removed.
Fixes may be made to master after release. Where possible these should be made to dev and 'git cherry-pick' used to merge forward; which preserves the commit info and prevents merge conflicts in the next cycle. Only rarely does a patch only apply to the master branch. If necessary this can be made. If the change is severe, the interface version number should be incremented. This is at the discretion of the community. In any event, a 'git pull' of the master branch should always result in the latest release with any post-release patches applied.
The interface number (the $z in $x.$y.$z) should be incremented in dev whenever a change is made which changes the interfaces or API in incompatible ways so that any external packages (especially addons and API clients) relying on a the current behaviour can discover and change their own interfaces accordingly at the point that it changed.
[h3]Git repository branches[/h3] [h3]Git repository branches[/h3]
There are two official branches of the $Projectname git repo. There are two official branches of the $Projectname git repo.
[list] [list]
[*] The stable version is maintained on the [*]*master** branch. The latest commit in this branch is considered to be suitable for production hubs. [*] The stable version is maintained on the [b]master[/b] branch. The latest commit in this branch is considered to be suitable for production hubs.
[*] Experimental development occurs on the **dev** branch, which is merged into **master** when it is deemed tested and stable enough. [*] Experimental development occurs on the [b]dev[/b] branch, which is merged into [b]master[/b] when it is deemed tested and stable enough.
[/list] [/list]
[h3]Developer tools and workflows[/h3] [h3]Developer tools and workflows[/h3]
[h4]Hub Snapshots[/h4] [h4]Hub Snapshots[/h4]
The [url=/help/admin/hub_snapshots]hub snapshots[/url] page provides instructions and scripts for taking complete snapshots of a hub to support switching between consistent and completely known states. This is useful to prevent situations where the content or database schema might be incompatible with the code. The [url=[baseurl]/help/admin/hub_snapshots]hub snapshots[/url] page provides instructions and scripts for taking complete snapshots of a hub to support switching between consistent and completely known states. This is useful to prevent situations where the content or database schema might be incompatible with the code.
[h3]Translations[/h3] [h3]Translations[/h3]
@ -44,18 +64,18 @@ currently not supported language, please register an account at transifex.com
and contact the Redmatrix translation team there. and contact the Redmatrix translation team there.
Translating $Projectname is simple. Just use the online tool at transifex. If you Translating $Projectname is simple. Just use the online tool at transifex. If you
don't want to deal with git & co. that is fine, we check the status of the don't want to deal with git & co. that is fine, we check the status of the[/td][/tr]
translations regularly and import them into the source tree at github so that [tr]ranslations regularly and import them into the source tree at github so that
others can use them. others can use them.
We do not include every translation from transifex in the source tree to avoid We do not include every translation from transifex in the source tree to avoid
a scattered and disturbed overall experience. As an uneducated guess we have a a scattered and disturbed overall experience. As an uneducated guess we have a
lower limit of 50% translated strings before we include the language. This lower limit of 50% translated strings before we include the language. This
limit is judging only by the amount of translated strings under the assumption limit is judging only by the amount of translated strings under the assumption[/td][/tr]
that the most prominent strings for the UI will be translated first by a [tr]hat the most prominent strings for the UI will be translated first by a[/td][/tr]
translation team. If you feel your translation useable before this limit, [tr]ranslation team. If you feel your translation useable before this limit,
please contact us and we will probably include your teams work in the source please contact us and we will probably include your teams work in the source[/td][/tr]
tree. [tr]ree.
If you want to get your work into the source tree yourself, feel free to do so If you want to get your work into the source tree yourself, feel free to do so
and contact us with and question that arises. The process is simple and and contact us with and question that arises. The process is simple and
@ -65,8 +85,8 @@ The location of the translated files in the source tree is
/view/LNG-CODE/ /view/LNG-CODE/
where LNG-CODE is the language code used, e.g. de for German or fr for French. where LNG-CODE is the language code used, e.g. de for German or fr for French.
For the email templates (the *.tpl files) just place them into the directory For the email templates (the *.tpl files) just place them into the directory
and you are done. The translated strings come as a "hmessages.po" file from and you are done. The translated strings come as a "hmessages.po" file from[/td][/tr]
transifex which needs to be translated into the PHP file $Projectname uses. To do [tr]ransifex which needs to be translated into the PHP file $Projectname uses. To do
so, place the file in the directory mentioned above and use the "po2php" so, place the file in the directory mentioned above and use the "po2php"
utility from the util directory of your $Projectname installation. utility from the util directory of your $Projectname installation.
@ -101,8 +121,8 @@ view/de/hmessages.po you would do the following.
[h4]Utilities[/h4] [h4]Utilities[/h4]
Additional to the po2php script there are some more utilities for translation Additional to the po2php script there are some more utilities for translation
in the "util" directory of the $Projectname source tree. If you only want to in the "util" directory of the $Projectname source tree. If you only want to[/td][/tr]
translate $Projectname into another language you wont need any of these tools most [tr]ranslate $Projectname into another language you wont need any of these tools most
likely but it gives you an idea how the translation process of $Projectname likely but it gives you an idea how the translation process of $Projectname
works. works.
@ -116,307 +136,43 @@ For further information see the utils/README file.
* the early translations are based on the friendica translations, if you * the early translations are based on the friendica translations, if you
some rough translations please let us know or fix them at Transifex. some rough translations please let us know or fix them at Transifex.
[h3]To-be-organized information[/h3] [h3]Licensing[/h3]
[b]Here is how you can join us.[/b]
First, get yourself a working git package on the system where you will be
doing development.
Create your own github account.
You may fork/clone the Red repository from [url=https://github.com/redmatrix/hubzilla.git]https://github.com/redmatrix/hubzilla.git[/url].
Follow the instructions provided here: [url=http://help.github.com/fork-a-repo/]Fork a Repo[/url]
to create and use your own tracking fork on github
Then go to your github page and create a "Pull request" when you are ready
to notify us to merge your work.
**Important**
Please pull in any changes from the project repository and merge them with your work **before** issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions.
Also - **test your changes**. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code.
**Licensing**
All code contributed to the project falls under the MIT license, unless otherwise specified. We will accept third-party code which falls under MIT, BSD and LGPL, but copyleft licensing (GPL, and AGPL) is only permitted in addons. It must be possible to completely remove the GPL (copyleft) code from the main project without breaking anything. All code contributed to the project falls under the MIT license, unless otherwise specified. We will accept third-party code which falls under MIT, BSD and LGPL, but copyleft licensing (GPL, and AGPL) is only permitted in addons. It must be possible to completely remove the GPL (copyleft) code from the main project without breaking anything.
**Coding Style** [h3]Coding Style[/h3]
In the interests of consistency we adopt the following code styling. We may accept patches using other styles, but where possible please try to provide a consistent code style. We aren't going to argue or debate the merits of this style, and it is irrelevant what project 'xyz' uses. This is not project 'xyz'. This is a baseline to try and keep the code readable now and in the future. In the interests of consistency we adopt the following code styling. We may accept patches using other styles, but where possible please try to provide a consistent code style. We aren't going to argue or debate the merits of this style, and it is irrelevant what project 'xyz' uses. This is not project 'xyz'. This is a baseline to try and keep the code readable now and in the future.
[list]
* All comments should be in English. [*]All comments should be in English.
[*]We use doxygen to generate documentation. This hasn't been consistently applied, but learning it and using it are highly encouraged.
* We use doxygen to generate documentation. This hasn't been consistently applied, but learning it and using it are highly encouraged. [*]Indentation is accomplished primarily with tabs using a tab-width of 4.
[*]String concatenation and operators should be separated by whitespace. e.g. "$foo = $bar . 'abc';" instead of "$foo=$bar.'abc';"
* Indentation is accomplished primarily with tabs using a tab-width of 4. [*]Generally speaking, we use single quotes for string variables and double quotes for SQL statements. "Here documents" should be avoided. Sometimes using double quoted strings with variable replacement is the most efficient means of creating the string. In most cases, you should be using single quotes.
[*]Use whitespace liberally to enhance readability. When creating arrays with many elements, we will often set one key/value pair per line, indented from the parent line appropriately. Lining up the assignment operators takes a bit more work, but also increases readability.
* String concatenation and operators should be separated by whitespace. e.g. "$foo = $bar . 'abc';" instead of "$foo=$bar.'abc';" [*]Generally speaking, opening braces go on the same line as the thing which opens the brace. They are the last character on the line. Closing braces are on a line by themselves.
[*]Some functions take arguments in argc/argv style like main() in C or function args in bash or Perl. Urls are broken up within a module. e.g, given "http://example.com/module/arg1/arg2", then $this->argc will be 3 (integer) and $this->argv will contain: [0] => 'module', [1] => 'arg1', [2] => 'arg2'. There will always be one argument. If provided a naked domain URL, $this->argv[0] is set to "home".
* Generally speaking, we use single quotes for string variables and double quotes for SQL statements. "Here documents" should be avoided. Sometimes using double quoted strings with variable replacement is the most efficient means of creating the string. In most cases, you should be using single quotes. [/list]
* Use whitespace liberally to enhance readability. When creating arrays with many elements, we will often set one key/value pair per line, indented from the parent line appropriately. Lining up the assignment operators takes a bit more work, but also increases readability. [h3]File system layout[/h3]
[table border=0]
* Generally speaking, opening braces go on the same line as the thing which opens the brace. They are the last character on the line. Closing braces are on a line by themselves. [th]Directory[/th][th]Description[/th][/tr]
[tr][td]addon[/td][td]optional addons/plugins[/td][/tr]
[tr][td]boot.php[/td][td]Every process uses this to bootstrap the application structure[/td][/tr]
**File system layout:** [tr][td]doc[/td][td]Help Files[/td][/tr]
[tr][td]images[/td][td]core required images[/td][/tr]
[addon] optional addons/plugins [tr][td]include[/td][td]The "model" in MVC - (back-end functions), also contains PHP "executables" for background processing[/td][/tr]
[tr][td]index.php[/td][td]The front-end controller for web access[/td][/tr]
[boot.php] Every process uses this to bootstrap the application structure [tr][td]install[/td][td]Installation and upgrade files and DB schema[/td][/tr]
[tr][td]library[/td][td]Third party modules (must be license compatible)[/td][/tr]
[doc] Help Files [tr][td]mod[/td][td]Controller modules based on URL pathname (e.g. [url=http://sitename/foo]http://sitename/foo[/url] loads mod/foo.php)[/td][/tr]
[tr][td]mod/site/[/td][td]site-specific mod overrides, excluded from git[/td][/tr]
[images] core required images [tr][td]util[/td][td]translation tools, main English string database and other miscellaneous utilities[/td][/tr]
[tr][td]version.inc[/td][td]contains current version (auto-updated via cron for the master repository and distributed via git)[/td][/tr]
[include] The "model" in MVC - (back-end functions), also contains PHP "executables" for background processing [tr][td]view[/td][td]theming and language files[/td][/tr]
[tr][td]view/(css,js,img,php,tpl)[/td][td]default theme files[/td][/tr]
[index.php] The front-end controller for web access [tr][td]view/(en,it,es ...)[/td][td]language strings and resources[/td][/tr]
[tr][td]view/theme/[/td][td]individual named themes containing (css,js,img,php,tpl) over-rides[/td][/tr]
[install] Installation and upgrade files and DB schema [/table]
[library] Third party modules (must be license compatible) [b][url=[baseurl]/help/developer/unorganized]More information needing re-organization and updating...[/url][/b]
[mod] Controller modules based on URL pathname (e.g. #^[url=http://sitename/foo]http://sitename/foo[/url] loads mod/foo.php)
[mod/site/] site-specific mod overrides, excluded from git
[util] translation tools, main English string database and other miscellaneous utilities
[version.inc] contains current version (auto-updated via cron for the master repository and distributed via git)
[view] theming and language files
[view/(css,js,img,php,tpl)] default theme files
[view/(en,it,es ...)] language strings and resources
[view/theme/] individual named themes containing (css,js,img,php,tpl) over-rides
**The Database:**
| Table | Description |
|-------------------------|--------------------------------------------------------|
| abconfig | contact table, replaces Friendica 'contact' |
| abook | |
| account | service provider account |
| addon | |
| addressbookchanges | |
| addressbooks | |
| app | |
| atoken | |
| attach | |
| auth_codes | |
| cache | |
| cal | |
| calendarchanges | |
| calendarinstances | |
| calendarobjects | |
| calendars | |
| calendarsubscriptions | |
| cards | |
| channel | |
| chat | |
| chatpresence | |
| chatroom | |
| clients | |
| config | |
| conv | |
| dreport | |
| event | |
| group_member | |
| groupmembers | |
| groups | |
| hook | |
| hubloc | |
| iconfig | |
| issue | |
| item | |
| item_id | |
| likes | |
| locks | |
| mail | |
| menu | |
| menu_item | |
| notify | |
| obj | |
| outq | |
| pconfig | personal (per channel) configuration storage |
| photo | |
| poll | |
| poll_elm | |
| principals | |
| profdef | |
| profext | |
| profile | |
| profile_check | |
| propertystorage | |
| register | |
| schedulingobjects | |
| session | |
| shares | |
| sign | |
| site | |
| source | |
| sys_perms | |
| term | |
| tokens | |
| updates | |
| users | |
| verify | |
| vote | |
| xchan | |
| xchat | |
| xconfig | |
| xign | |
| xlink | |
| xperm | |
| xprof | |
| xtag | |
* abook - contact table, replaces Friendica 'contact'
* account - service provider account
* addon - registered plugins
* app - peronal app data
* attach - file attachments
* auth_codes - OAuth usage
* cache - OEmbed cache
* channel - replaces Friendica 'user'
* chat - chat room content
* chatpresence - channel presence information for chat
* chatroom - data for the actual chat room
* clients - OAuth usage
* config - main configuration storage
* conv - Diaspora private messages
* event - Events
* fcontact - friend suggestion stuff
* ffinder - friend suggestion stuff
* fserver - obsolete
* fsuggest - friend suggestion stuff
* groups - privacy groups
* group_member - privacy groups
* hook - plugin hook registry
* hubloc - Red location storage, ties a location to an xchan
* item - posts
* item_id - other identifiers on other services for posts
* likes - likes of 'things'
* mail - private messages
* menu - channel menu data
* menu_item - items uses by channel menus
* notify - notifications
* notify-threads - need to factor this out and use item thread info on notifications
* obj - object data for things (x has y)
* outq - output queue
* pconfig - personal (per channel) configuration storage
* photo - photo storage
* poll - data for polls
* poll_elm - data for poll elements
* profdef - custom profile field definitions
* profext - custom profile field data
* profile - channel profiles
* profile_check - DFRN remote auth use, may be obsolete
* register - registrations requiring admin approval
* session - web session storage
* shares - shared item information
* sign - Diaspora signatures. To be phased out.
* site - site table to find directory peers
* source - channel sources data
* spam - unfinished
* sys_perms - extensible permissions for the sys channel
* term - item taxonomy (categories, tags, etc.) table
* tokens - OAuth usage
* updates - directory sync updates
* verify - general purpose verification structure
* vote - vote data for polls
* xchan - replaces 'gcontact', list of known channels in the universe
* xchat - bookmarked chat rooms
* xconfig - as pconfig but for channels with no local account
* xlink - "friends of friends" linkages derived from poco
* xprof - if this hub is a directory server, contains basic public profile info of everybody in the network
* xtag - if this hub is a directory server, contains tags or interests of everybody in the network
**How to theme $Projectname**
This is a short documentation on what I found while trying to modify $Projectname's appearance.
First, you'll need to create a new theme. This is in /view/theme, and I chose to copy 'redbasic' since it's the only available for now. Let's assume I named it .
Oh, and don't forget to rename the _init function in /php/theme.php to be _init() instead of redbasic_init().
At that point, if you need to add javascript or css files, add them to /js or /css, and then "register" them in _init() through head_add_js('file.js') and head_add_css('file.css').
Now you'll probably want to alter a template. These can be found in in /view/tpl OR view//tpl. All you should have to do is copy whatever you want to tweak from the first place to your theme's own tpl directory.
We're pretty relaxed when it comes to developers. We don't have a lot of rules. Some of us are over-worked and if you want to help we're happy to let you help. That said, attention to a few guidelines will make the process smoother and make it easier to work together. We have developers from across the globe with different abilities and different cultural backgrounds and different levels of patience. Our primary rule is to respect others. Sometimes this is hard and sometimes we have very different opinions of how things should work, but if everybody makes an effort, we'll get along just fine.
**Here is how you can join us.**
First, get yourself a working git package on the system where you will be
doing development.
Create your own github account.
You may fork/clone the Red repository from [url=https://github.com/redmatrix/hubzilla.git]https://github.com/redmatrix/hubzilla.git[/url]
Follow the instructions provided here: [url=http://help.github.com/fork-a-repo/]http://help.github.com/fork-a-repo/[/url]
to create and use your own tracking fork on github
Then go to your github page and create a "Pull request" when you are ready
to notify us to merge your work.
**Translations**
Our translations are managed through Transifex. If you wish to help out translating the $Projectname to another language, sign up on transifex.com, visit [url=https://www.transifex.com/Friendica/red-matrix/]https://www.transifex.com/Friendica/red-matrix/[/url] and request to join one of the existing language teams or create a new one. Notify one of the core developers when you have a translation update which requires merging, or ask about merging it yourself if you're comfortable with git and PHP. We have a string file called 'messages.po' which is gettext compliant and a handful of email templates, and from there we automatically generate the application's language files.
**Important**
Please pull in any changes from the project repository and merge them with your work **before** issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions.
Also - **test your changes**. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code.
Further documentation can be found at the Github wiki pages at: [url=https://github.com/friendica/red/wiki]https://github.com/friendica/red/wiki[/url]
**Licensing**
All code contributed to the project falls under the MIT license, unless otherwise specified. We will accept third-party code which falls under MIT, BSD and LGPL, but copyleft licensing (GPL, and AGPL) is only permitted in addons. It must be possible to completely remove the GPL (copyleft) code from the main project without breaking anything.
**Concensus Building**
Code changes which fix an obvious bug are pretty straight-forward. For instance if you click "Save" and the thing you're trying to save isn't saved, it's fairly obvious what the intended behaviour should be. Often when developing feature requests, it may affect large numbers of community members and it's possible that other members of the community won't agree with the need for the feature, or with your proposed implementation. They may not see something as a bug or a desirable feature.
We encourage consensus building within the community when it comes to any feature which might be considered controversial or where there isn't unanimous decision that the proposed feature is the correct way to accomplish the task. The first place to pitch your ideas is to [url=https://zothub.com/channel/one]Channel One[/url]. Others may have some input or be able to point out facets of your concept which might be problematic in our environment. But also, you may encounter opposition to your plan. This doesn't mean you should stop and/or ignore the feature. Listen to the concerns of others and try and work through any implementation issues.
There are places where opposition cannot be resolved. In these cases, please consider making your feature **optional** or non-default behaviour that must be specifically enabled. This technique can often be used when a feature has significant but less than unanimous support. Those who desire the feature can turn it on and those who don't want it - will leave it turned off.
If a feature uses other networks or websites and or is only seen as desirable by a small minority of the community, consider making the functionality available via an addon or plugin. Once again, those who don't desire the feature won't need to install it. Plugins are relatively easy to create and "hooks" can be easily added or modified if the current hooks do not do what is needed to allow your plugin to work.
**Coding Style**
In the interests of consistency we adopt the following code styling. We may accept patches using other styles, but where possible please try to provide a consistent code style. We aren't going to argue or debate the merits of this style, and it is irrelevant what project 'xyz' uses. This is not project 'xyz'. This is a baseline to try and keep the code readable now and in the future.
* All comments should be in English.
* We use doxygen to generate documentation. This hasn't been consistently applied, but learning it and using it are highly encouraged.
* Indentation is accomplished primarily with tabs using a tab-width of 4.
* String concatenation and operators should be separated by whitespace. e.g. "$foo = $bar . 'abc';" instead of "$foo=$bar.'abc';"
* Generally speaking, we use single quotes for string variables and double quotes for SQL statements. "Here documents" should be avoided. Sometimes using double quoted strings with variable replacement is the most efficient means of creating the string. In most cases, you should be using single quotes.
* Use whitespace liberally to enhance readability. When creating arrays with many elements, we will often set one key/value pair per line, indented from the parent line appropriately. Lining up the assignment operators takes a bit more work, but also increases readability.
* Generally speaking, opening braces go on the same line as the thing which opens the brace. They are the last character on the line. Closing braces are on a line by themselves.
* Some functions take arguments in argc/argv style like main() in C or function args in bash or Perl. Urls are broken up within a module. e.g, given "http://example.com/module/arg1/arg2", then $this->argc will be 3 (integer) and $this->argv will contain: [0] => 'module', [1] => 'arg1', [2] => 'arg2'. There will always be one argument. If provided a naked domain URL, $this->argv[0] is set to "home".

422
doc/developer/developer_guide_original.md
View File

@ -1,422 +0,0 @@
### Who is a Hubzilla developer? Should I read this?
Anyone who contributes to making Hubzilla better is a developer. There are many different and important ways you can contribute to this amazing technology, _even if you do not know how to write code_. The software itself is only a part of the Hubzilla project. You can contribute by
* translating text to your language so that people around the world have the opportunity to use Hubzilla
* promoting Hubzilla and spreading awareness of the platform through blog posts, articles, and word-of-mouth
* creating artwork and graphics for project assets such as icons and marketing material
* supporting project infrastructure like the project website and demo servers
_Software_ developers are of course welcomed; there are so many great ideas to implement and not enough people to make them all a reality! The Hubzilla code base is an advanced and mature system, but the platform is still very flexible and responsive to new ideas.
This document will help you get started learning and contributing to Hubzilla.
### Versioning system
The versioning system is similar to the popular semantic versioning but less stringent. Given x.y.z, x changes yearly. y changes for "stable" monthly builds, and z increments when there are interface changes. We maintain our date and build numbers for medium grain version control (commits within a certain date range) and of course git revs for fine grained control.
### Git repository branches
There are two official branches of the Hubzilla git repo.
* The stable version is maintained on the **master** branch. The latest commit in this branch is considered to be suitable for production hubs.
* Experimental development occurs on the **dev** branch, which is merged into **master** when it is deemed tested and stable enough.
### Developer tools and workflows
#### Hub Snapshots
The [hub snapshots](/help/admin/hub_snapshots) page provides instructions and scripts for taking complete
snapshots of a hub to support switching between consistent and completely known
states. This is useful to prevent situations where the content or database schema
might be incompatible with the code.
### Translations
Our translations are managed through Transifex. If you wish to help out translating Hubzilla to another language, sign up on transifex.com, visit [https://www.transifex.com/projects/p/red-matrix/](https://www.transifex.com/projects/p/red-matrix/) and request to join one of the existing language teams or create a new one. Notify one of the core developers when you have a translation update which requires merging, or ask about merging it yourself if you're comfortable with git and PHP. We have a string file called 'messages.po' which is gettext compliant and a handful of email templates, and from there we automatically generate the application's language files.
#### Translation Process
The strings used in the UI of Hubzilla is translated at [Transifex][1] and then
included in the git repository at github. If you want to help with translation
for any language, be it correcting terms or translating Hubzilla to a
currently not supported language, please register an account at transifex.com
and contact the Redmatrix translation team there.
Translating Hubzilla is simple. Just use the online tool at transifex. If you
don't want to deal with git & co. that is fine, we check the status of the
translations regularly and import them into the source tree at github so that
others can use them.
We do not include every translation from transifex in the source tree to avoid
a scattered and disturbed overall experience. As an uneducated guess we have a
lower limit of 50% translated strings before we include the language. This
limit is judging only by the amount of translated strings under the assumption
that the most prominent strings for the UI will be translated first by a
translation team. If you feel your translation useable before this limit,
please contact us and we will probably include your teams work in the source
tree.
If you want to get your work into the source tree yourself, feel free to do so
and contact us with and question that arises. The process is simple and
Hubzilla ships with all the tools necessary.
The location of the translated files in the source tree is
/view/LNG-CODE/
where LNG-CODE is the language code used, e.g. de for German or fr for French.
For the email templates (the *.tpl files) just place them into the directory
and you are done. The translated strings come as a "hmessages.po" file from
transifex which needs to be translated into the PHP file Hubzilla uses. To do
so, place the file in the directory mentioned above and use the "po2php"
utility from the util directory of your Hubzilla installation.
Assuming you want to convert the German localization which is placed in
view/de/hmessages.po you would do the following.
1. Navigate at the command prompt to the base directory of your
Hubzilla installation
2. Execute the po2php script, which will place the translation
in the hstrings.php file that is used by Hubzilla.
$> php util/po2php.php view/de/hmessages.po
The output of the script will be placed at view/de/hstrings.php where
froemdoca os expecting it, so you can test your translation mmediately.
3. Visit your Hubzilla page to check if it still works in the language you
just translated. If not try to find the error, most likely PHP will give
you a hint in the log/warnings.about the error.
For debugging you can also try to "run" the file with PHP. This should
not give any output if the file is ok but might give a hint for
searching the bug in the file.
$> php view/de/hstrings.php
4. commit the two files with a meaningful commit message to your git
repository, push it to your fork of the Hubzilla repository at github and
issue a pull request for that commit.
#### Utilities
Additional to the po2php script there are some more utilities for translation
in the "util" directory of the Hubzilla source tree. If you only want to
translate Hubzilla into another language you wont need any of these tools most
likely but it gives you an idea how the translation process of Hubzilla
works.
For further information see the utils/README file.
#### Known Problems
* Hubzilla uses the language setting of the visitors browser to determain the
language for the UI. Most of the time this works, but there are some known
quirks.
* the early translations are based on the friendica translations, if you
some rough translations please let us know or fix them at Transifex.
### To-be-organized information
**Here is how you can join us.**
First, get yourself a working git package on the system where you will be
doing development.
Create your own github account.
You may fork/clone the Red repository from [https://github.com/redmatrix/hubzilla.git](https://github.com/redmatrix/hubzilla.git).
Follow the instructions provided here: [http://help.github.com/fork-a-repo/](http://help.github.com/fork-a-repo/)
to create and use your own tracking fork on github
Then go to your github page and create a "Pull request" when you are ready
to notify us to merge your work.
**Important**
Please pull in any changes from the project repository and merge them with your work **before** issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions.
Also - **test your changes**. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code.
**Licensing**
All code contributed to the project falls under the MIT license, unless otherwise specified. We will accept third-party code which falls under MIT, BSD and LGPL, but copyleft licensing (GPL, and AGPL) is only permitted in addons. It must be possible to completely remove the GPL (copyleft) code from the main project without breaking anything.
**Coding Style**
In the interests of consistency we adopt the following code styling. We may accept patches using other styles, but where possible please try to provide a consistent code style. We aren't going to argue or debate the merits of this style, and it is irrelevant what project 'xyz' uses. This is not project 'xyz'. This is a baseline to try and keep the code readable now and in the future.
* All comments should be in English.
* We use doxygen to generate documentation. This hasn't been consistently applied, but learning it and using it are highly encouraged.
* Indentation is accomplished primarily with tabs using a tab-width of 4.
* String concatenation and operators should be separated by whitespace. e.g. "$foo = $bar . 'abc';" instead of "$foo=$bar.'abc';"
* Generally speaking, we use single quotes for string variables and double quotes for SQL statements. "Here documents" should be avoided. Sometimes using double quoted strings with variable replacement is the most efficient means of creating the string. In most cases, you should be using single quotes.
* Use whitespace liberally to enhance readability. When creating arrays with many elements, we will often set one key/value pair per line, indented from the parent line appropriately. Lining up the assignment operators takes a bit more work, but also increases readability.
* Generally speaking, opening braces go on the same line as the thing which opens the brace. They are the last character on the line. Closing braces are on a line by themselves.
**File system layout:**
[addon] optional addons/plugins
[boot.php] Every process uses this to bootstrap the application structure
[doc] Help Files
[images] core required images
[include] The "model" in MVC - (back-end functions), also contains PHP "executables" for background processing
[index.php] The front-end controller for web access
[install] Installation and upgrade files and DB schema
[library] Third party modules (must be license compatible)
[mod] Controller modules based on URL pathname (e.g. #^[url=http://sitename/foo]http://sitename/foo[/url] loads mod/foo.php)
[mod/site/] site-specific mod overrides, excluded from git
[util] translation tools, main English string database and other miscellaneous utilities
[version.inc] contains current version (auto-updated via cron for the master repository and distributed via git)
[view] theming and language files
[view/(css,js,img,php,tpl)] default theme files
[view/(en,it,es ...)] language strings and resources
[view/theme/] individual named themes containing (css,js,img,php,tpl) over-rides
**The Database:**
| Table | Description |
|-------------------------|--------------------------------------------------------|
| abconfig | contact table, replaces Friendica 'contact' |
| abook | |
| account | service provider account |
| addon | |
| addressbookchanges | |
| addressbooks | |
| app | |
| atoken | |
| attach | |
| auth_codes | |
| cache | |
| cal | |
| calendarchanges | |
| calendarinstances | |
| calendarobjects | |
| calendars | |
| calendarsubscriptions | |
| cards | |
| channel | |
| chat | |
| chatpresence | |
| chatroom | |
| clients | |
| config | |
| conv | |
| dreport | |
| event | |
| group_member | |
| groupmembers | |
| groups | |
| hook | |
| hubloc | |
| iconfig | |
| issue | |
| item | |
| item_id | |
| likes | |
| locks | |
| mail | |
| menu | |
| menu_item | |
| notify | |
| obj | |
| outq | |
| pconfig | personal (per channel) configuration storage |
| photo | |
| poll | |
| poll_elm | |
| principals | |
| profdef | |
| profext | |
| profile | |
| profile_check | |
| propertystorage | |
| register | |
| schedulingobjects | |
| session | |
| shares | |
| sign | |
| site | |
| source | |
| sys_perms | |
| term | |
| tokens | |
| updates | |
| users | |
| verify | |
| vote | |
| xchan | |
| xchat | |
| xconfig | |
| xign | |
| xlink | |
| xperm | |
| xprof | |
| xtag | |
* abook - contact table, replaces Friendica 'contact'
* account - service provider account
* addon - registered plugins
* app - peronal app data
* attach - file attachments
* auth_codes - OAuth usage
* cache - OEmbed cache
* channel - replaces Friendica 'user'
* chat - chat room content
* chatpresence - channel presence information for chat
* chatroom - data for the actual chat room
* clients - OAuth usage
* config - main configuration storage
* conv - Diaspora private messages
* event - Events
* fcontact - friend suggestion stuff
* ffinder - friend suggestion stuff
* fserver - obsolete
* fsuggest - friend suggestion stuff
* groups - privacy groups
* group_member - privacy groups
* hook - plugin hook registry
* hubloc - Red location storage, ties a location to an xchan
* item - posts
* item_id - other identifiers on other services for posts
* likes - likes of 'things'
* mail - private messages
* menu - channel menu data
* menu_item - items uses by channel menus
* notify - notifications
* notify-threads - need to factor this out and use item thread info on notifications
* obj - object data for things (x has y)
* outq - output queue
* pconfig - personal (per channel) configuration storage
* photo - photo storage
* poll - data for polls
* poll_elm - data for poll elements
* profdef - custom profile field definitions
* profext - custom profile field data
* profile - channel profiles
* profile_check - DFRN remote auth use, may be obsolete
* register - registrations requiring admin approval
* session - web session storage
* shares - shared item information
* sign - Diaspora signatures. To be phased out.
* site - site table to find directory peers
* source - channel sources data
* spam - unfinished
* sys_perms - extensible permissions for the sys channel
* term - item taxonomy (categories, tags, etc.) table
* tokens - OAuth usage
* updates - directory sync updates
* verify - general purpose verification structure
* vote - vote data for polls
* xchan - replaces 'gcontact', list of known channels in the universe
* xchat - bookmarked chat rooms
* xconfig - as pconfig but for channels with no local account
* xlink - "friends of friends" linkages derived from poco
* xprof - if this hub is a directory server, contains basic public profile info of everybody in the network
* xtag - if this hub is a directory server, contains tags or interests of everybody in the network
**How to theme Hubzilla**
This is a short documentation on what I found while trying to modify Hubzilla's appearance.
First, you'll need to create a new theme. This is in /view/theme, and I chose to copy 'redbasic' since it's the only available for now. Let's assume I named it .
Oh, and don't forget to rename the _init function in /php/theme.php to be _init() instead of redbasic_init().
At that point, if you need to add javascript or css files, add them to /js or /css, and then "register" them in _init() through head_add_js('file.js') and head_add_css('file.css').
Now you'll probably want to alter a template. These can be found in in /view/tpl OR view//tpl. All you should have to do is copy whatever you want to tweak from the first place to your theme's own tpl directory.
We're pretty relaxed when it comes to developers. We don't have a lot of rules. Some of us are over-worked and if you want to help we're happy to let you help. That said, attention to a few guidelines will make the process smoother and make it easier to work together. We have developers from across the globe with different abilities and different cultural backgrounds and different levels of patience. Our primary rule is to respect others. Sometimes this is hard and sometimes we have very different opinions of how things should work, but if everybody makes an effort, we'll get along just fine.
**Here is how you can join us.**
First, get yourself a working git package on the system where you will be
doing development.
Create your own github account.
You may fork/clone the Red repository from [url=https://github.com/redmatrix/hubzilla.git]https://github.com/redmatrix/hubzilla.git[/url]
Follow the instructions provided here: [url=http://help.github.com/fork-a-repo/]http://help.github.com/fork-a-repo/[/url]
to create and use your own tracking fork on github
Then go to your github page and create a "Pull request" when you are ready
to notify us to merge your work.
**Translations**
Our translations are managed through Transifex. If you wish to help out translating the $Projectname to another language, sign up on transifex.com, visit [url=https://www.transifex.com/projects/p/red-matrix/]https://www.transifex.com/projects/p/red-matrix/[/url] and request to join one of the existing language teams or create a new one. Notify one of the core developers when you have a translation update which requires merging, or ask about merging it yourself if you're comfortable with git and PHP. We have a string file called 'messages.po' which is gettext compliant and a handful of email templates, and from there we automatically generate the application's language files.
**Important**
Please pull in any changes from the project repository and merge them with your work **before** issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions.
Also - **test your changes**. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code.
Further documentation can be found at the Github wiki pages at: [url=https://github.com/friendica/red/wiki]https://github.com/friendica/red/wiki[/url]
**Licensing**
All code contributed to the project falls under the MIT license, unless otherwise specified. We will accept third-party code which falls under MIT, BSD and LGPL, but copyleft licensing (GPL, and AGPL) is only permitted in addons. It must be possible to completely remove the GPL (copyleft) code from the main project without breaking anything.
**Concensus Building**
Code changes which fix an obvious bug are pretty straight-forward. For instance if you click "Save" and the thing you're trying to save isn't saved, it's fairly obvious what the intended behaviour should be. Often when developing feature requests, it may affect large numbers of community members and it's possible that other members of the community won't agree with the need for the feature, or with your proposed implementation. They may not see something as a bug or a desirable feature.
We encourage consensus building within the community when it comes to any feature which might be considered controversial or where there isn't unanimous decision that the proposed feature is the correct way to accomplish the task. The first place to pitch your ideas is to [url=https://zothub.com/channel/one]Channel One[/url]. Others may have some input or be able to point out facets of your concept which might be problematic in our environment. But also, you may encounter opposition to your plan. This doesn't mean you should stop and/or ignore the feature. Listen to the concerns of others and try and work through any implementation issues.
There are places where opposition cannot be resolved. In these cases, please consider making your feature **optional** or non-default behaviour that must be specifically enabled. This technique can often be used when a feature has significant but less than unanimous support. Those who desire the feature can turn it on and those who don't want it - will leave it turned off.
If a feature uses other networks or websites and or is only seen as desirable by a small minority of the community, consider making the functionality available via an addon or plugin. Once again, those who don't desire the feature won't need to install it. Plugins are relatively easy to create and "hooks" can be easily added or modified if the current hooks do not do what is needed to allow your plugin to work.
**Coding Style**
In the interests of consistency we adopt the following code styling. We may accept patches using other styles, but where possible please try to provide a consistent code style. We aren't going to argue or debate the merits of this style, and it is irrelevant what project 'xyz' uses. This is not project 'xyz'. This is a baseline to try and keep the code readable now and in the future.
* All comments should be in English.
* We use doxygen to generate documentation. This hasn't been consistently applied, but learning it and using it are highly encouraged.
* Indentation is accomplished primarily with tabs using a tab-width of 4.
* String concatenation and operators should be separated by whitespace. e.g. "$foo = $bar . 'abc';" instead of "$foo=$bar.'abc';"
* Generally speaking, we use single quotes for string variables and double quotes for SQL statements. "Here documents" should be avoided. Sometimes using double quoted strings with variable replacement is the most efficient means of creating the string. In most cases, you should be using single quotes.
* Use whitespace liberally to enhance readability. When creating arrays with many elements, we will often set one key/value pair per line, indented from the parent line appropriately. Lining up the assignment operators takes a bit more work, but also increases readability.
* Generally speaking, opening braces go on the same line as the thing which opens the brace. They are the last character on the line. Closing braces are on a line by themselves.
* Some functions take arguments in argc/argv style like main() in C or function args in bash or Perl. Urls are broken up within a module. e.g, given "http://example.com/module/arg1/arg2", then $this->argc will be 3 (integer) and $this->argv will contain: [0] => 'module', [1] => 'arg1', [2] => 'arg2'. There will always be one argument. If provided a naked domain URL, $this->argv[0] is set to "home".

73
doc/developer/unorganized.md Normal file
View File

@ -0,0 +1,73 @@
### To-be-organized information
**Here is how you can join us.**
First, get yourself a working git package on the system where you will be
doing development.
Create your own github account.
You may fork/clone the Red repository from [https://github.com/redmatrix/hubzilla.git](https://github.com/redmatrix/hubzilla.git).
Follow the instructions provided here: [http://help.github.com/fork-a-repo/](http://help.github.com/fork-a-repo/)
to create and use your own tracking fork on github
Then go to your github page and create a "Pull request" when you are ready
to notify us to merge your work.
**Important**
Please pull in any changes from the project repository and merge them with your work **before** issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions.
Also - **test your changes**. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code.
**How to theme Hubzilla**
This is a short documentation on what I found while trying to modify Hubzilla's appearance.
First, you'll need to create a new theme. This is in /view/theme, and I chose to copy 'redbasic' since it's the only available for now. Let's assume I named it .
Oh, and don't forget to rename the _init function in /php/theme.php to be _init() instead of redbasic_init().
At that point, if you need to add javascript or css files, add them to /js or /css, and then "register" them in _init() through head_add_js('file.js') and head_add_css('file.css').
Now you'll probably want to alter a template. These can be found in in /view/tpl OR view//tpl. All you should have to do is copy whatever you want to tweak from the first place to your theme's own tpl directory.
We're pretty relaxed when it comes to developers. We don't have a lot of rules. Some of us are over-worked and if you want to help we're happy to let you help. That said, attention to a few guidelines will make the process smoother and make it easier to work together. We have developers from across the globe with different abilities and different cultural backgrounds and different levels of patience. Our primary rule is to respect others. Sometimes this is hard and sometimes we have very different opinions of how things should work, but if everybody makes an effort, we'll get along just fine.
**Here is how you can join us.**
First, get yourself a working git package on the system where you will be
doing development.
Create your own github account.
You may fork/clone the Red repository from [url=https://github.com/redmatrix/hubzilla.git]https://github.com/redmatrix/hubzilla.git[/url]
Follow the instructions provided here: [url=http://help.github.com/fork-a-repo/]http://help.github.com/fork-a-repo/[/url]
to create and use your own tracking fork on github
Then go to your github page and create a "Pull request" when you are ready
to notify us to merge your work.
**Important**
Please pull in any changes from the project repository and merge them with your work **before** issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions.
Also - **test your changes**. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code.
Further documentation can be found at the Github wiki pages at: [url=https://github.com/friendica/red/wiki]https://github.com/friendica/red/wiki[/url]
**Concensus Building**
Code changes which fix an obvious bug are pretty straight-forward. For instance if you click "Save" and the thing you're trying to save isn't saved, it's fairly obvious what the intended behaviour should be. Often when developing feature requests, it may affect large numbers of community members and it's possible that other members of the community won't agree with the need for the feature, or with your proposed implementation. They may not see something as a bug or a desirable feature.
We encourage consensus building within the community when it comes to any feature which might be considered controversial or where there isn't unanimous decision that the proposed feature is the correct way to accomplish the task. The first place to pitch your ideas is to [url=https://zothub.com/channel/one]Channel One[/url]. Others may have some input or be able to point out facets of your concept which might be problematic in our environment. But also, you may encounter opposition to your plan. This doesn't mean you should stop and/or ignore the feature. Listen to the concerns of others and try and work through any implementation issues.
There are places where opposition cannot be resolved. In these cases, please consider making your feature **optional** or non-default behaviour that must be specifically enabled. This technique can often be used when a feature has significant but less than unanimous support. Those who desire the feature can turn it on and those who don't want it - will leave it turned off.
If a feature uses other networks or websites and or is only seen as desirable by a small minority of the community, consider making the functionality available via an addon or plugin. Once again, those who don't desire the feature won't need to install it. Plugins are relatively easy to create and "hooks" can be easily added or modified if the current hooks do not do what is needed to allow your plugin to work.

19
doc/feature/saved_search.bb
View File

@ -1,19 +0,0 @@
[h2]Saved Searches[/h2]
In order to quickly find information, the 'saved search' widget may be used. This widget may be presented as a sidebar tool on your network page and possibly from your channel page. It is differentiated from the 'navigation bar' search tool in that it does not search the entire site, but only the subset of information available to your channel.
Additionally the search terms you provide may activate a one-tme search or be saved in a list for re-use. Saving the search item also invokes the search in addition to adding it to the saved list (which is displayed below the search text entry box). Any item in the list may be discarded if it is no longer needed.
The saved search widget will provide autocompletion of channels (the results are prefixed with '@'), and hashtags (prefixed with '#'). You do not need to enter these tags; although entering the desired tag will reduce the autocomplete results to only hold the relevant information. The behaviour maps as follows:
[ul]
[li]@name - search your network stream for posts or comments written by 'name'. This will also change the post editor permissions to include only 'name'; as if this was a privacy group.[/li]
[li]#hashtag - search you network stream for posts containing #hashtag.[/li]
[li]text - search your network stream for posts containing 'text'.[/li]
[/li]

15
doc/feature/techlevels.bb
View File

@ -1,15 +0,0 @@
[h2]Techlevels[/h2]
Techlevels is a unique feature of Hubzilla 'pro'. It is not available in other server_roles, although it expands on the concepts introduced in Hubzilla 'basic'.
[h3]Background[/h3]
We've implemented several different mechanisms in order to reduce the apparent complexity and learning curve presented to new members. At the same time, we do not wish to limit any functionality for people who are able to grasp some slightly advanced technical technical features. The first mechanism was to move several features to an optional 'Features' page where they could be enabled at will; with the default interface kept somewhat lean.
The problem we had now is that the number of features began to grow dramatically, and the Feature page is daunting in possibilities. There are also features present which probably should not be available to all members, but may be extremely useful to those with technical backgrounds.
The techlevels seeeks to remedy this by grouping features within different levels of technical ability; starting at 0 (uncomfortable with technology), and up to 5 (Unix wizard or equivalent).
When a new member registers, their account is provided a techlevel setting of 0. On the account settings page they may change this to any available level. A higher level opens more advanced features and possible interactions.
The account administrator may also lock a particular level, lock a maximum level, or change/re-arrange the features available to any level. Those with the minimum level are typically not very exploratory and are unlikely to discover the advanced modes. This is by design. Those that look around and desire more interactions will find them. In the absence of administrator defaults they may choose any level. As they look at the features available to the level in question, it is generally expected that they will discover some features are beyond their comprehension and it is hoped they will back off to a level where the interface and features are comfortable to their skill level. This is somewhat experimental at present and for that reason is not part of the 'standard' server role. The standard server role is preset to level '5', and the basic server role is preset to level '0', with no possibility of change. Members in these roles may find themselves overwhelmed or underwhelmed by the feature set and complexity.

18
doc/member/member_guide.bb
View File

@ -294,8 +294,11 @@ To create and manage guest tokens, open the [zrl=[baseurl]/settings/tokens/]Gues
Additional permissions may be granted to the guest token by expanding the [b]Individual Permissions[/b] options and selecting privacy settings such as [b]Can view my channel stream and posts[/b] or [b]Can chat with me[/b]. Additional permissions may be granted to the guest token by expanding the [b]Individual Permissions[/b] options and selecting privacy settings such as [b]Can view my channel stream and posts[/b] or [b]Can chat with me[/b].
[url=[baseurl]/help/feature/access_tokens]More details can be found here...[/url]
[img][baseurl]/doc/member/assets/zat_dialog.png[/img] [img][baseurl]/doc/member/assets/zat_dialog.png[/img]
[h3]Markup Languages[/h3] [h3]Markup Languages[/h3]
$Projectname supports several markup languages for advanced formatting of content. The default markup language is a [url=[baseurl]/help/member/bbcode]custom variant of BBcode[/url], tailored for use in $Projectname. [url=[baseurl]/help/member/bbcode]BBcode[/url] is supported for posts, wiki pages, and web page elements. Wiki pages and webpage elements may also be written using standard Markdown. $Projectname supports several markup languages for advanced formatting of content. The default markup language is a [url=[baseurl]/help/member/bbcode]custom variant of BBcode[/url], tailored for use in $Projectname. [url=[baseurl]/help/member/bbcode]BBcode[/url] is supported for posts, wiki pages, and web page elements. Wiki pages and webpage elements may also be written using standard Markdown.
[table border=0] [table border=0]
@ -969,6 +972,21 @@ Once open you can set a bookmark.
Note: There have been reported issues with clients that use "chunked transfer encoding", which includes Apple iOS services, and also the "AnyClient" and "CyberDuck" tools. These work fine for downloads, but uploads often end up with files of zero size. This is caused by an incorrect implemention of chunked encoding in some current FCGI (fast-cgi) implementations. Apache running with PHP as a module does not have these issues, but when running under FCGI you may need to use alternative clients or use the web uploader. At the time of this writing the issue has been open and no updates provided for at least a year. If you encounter zero size files with other clients, please check the client notes; as there are occasional configuration issues which can also produce these symptoms. Note: There have been reported issues with clients that use "chunked transfer encoding", which includes Apple iOS services, and also the "AnyClient" and "CyberDuck" tools. These work fine for downloads, but uploads often end up with files of zero size. This is caused by an incorrect implemention of chunked encoding in some current FCGI (fast-cgi) implementations. Apache running with PHP as a module does not have these issues, but when running under FCGI you may need to use alternative clients or use the web uploader. At the time of this writing the issue has been open and no updates provided for at least a year. If you encounter zero size files with other clients, please check the client notes; as there are occasional configuration issues which can also produce these symptoms.
[h3]Saved Searches[/h3]
In order to quickly find information, the 'saved search' widget may be used. This widget may be presented as a sidebar tool on your network page and possibly from your channel page. It is differentiated from the 'navigation bar' search tool in that it does not search the entire site, but only the subset of information available to your channel.
Additionally the search terms you provide may activate a one-time search or be saved in a list for re-use. Saving the search item also invokes the search in addition to adding it to the saved list (which is displayed below the search text entry box). Any item in the list may be discarded if it is no longer needed.
The saved search widget will provide autocompletion of channels (the results are prefixed with '@'), and hashtags (prefixed with '#'). You do not need to enter these tags; although entering the desired tag will reduce the autocomplete results to only hold the relevant information. The behaviour maps as follows:
[list]
[*]@name - search your network stream for posts or comments written by 'name'. This will also change the post editor permissions to include only 'name'; as if this was a privacy group.
[*]#hashtag - search you network stream for posts containing #hashtag.
[*]text - search your network stream for posts containing 'text'.
[/list]
[h3]Remove Channel or Account[/h3] [h3]Remove Channel or Account[/h3]
[h4]Remove Channel[/h4] [h4]Remove Channel[/h4]

29
doc/project/governance.bb
View File

@ -1,29 +0,0 @@
[h2]$Projectname Governance[/h2]
Governance relates to the management of a project and particularly how this relates to conflict resolution.
[h3]Community Governance[/h3]
The project is maintained and decisions made by the 'community'. The governance structure is still evolving. Until the structure is finalised, decisions are made in the following order:
[ol]
[*] Lazy Consensus
If a project proposal is made to one of the community governance forums and there are no serious objections in a "reasonable" amount of time from date of proposal (we usually provide 2-3 days for all interested parties to weigh in), no vote needs to be taken and the proposal will be considered approved. Some concerns may be raised at this time, but if these are addressed during discussion and work-arounds provided, it will still be considered approved.
[*] Veto
Senior developers with a significant history of project commits may veto any decision. The decision may not proceed until the veto is removed or an alternative proposal is presented.
[*] Community Vote
A decision which does not have a clear mandate or clear consensus, but is not vetoed, can be taken to a community vote. At present this is a simple popular vote in one of the applicable community forums. At this time, popular vote decides the outcome. This may change in the future if the community adopts a 'council' governance model. This document will be updated at that time with the updated governance rules.
[/ol]
Community Voting does not always provide a pleasant outcome and can generate polarised factions in the community (hence the reason why other models are under consideration). If the proposal is 'down voted' there are still several things which can be done and the proposal re-submitted with slightly different parameters (convert to an addon, convert to an optional feature which is disabled by default, etc.). If interest in the feature is high and the vote is "close", it can generate lots of bad feelings amongst the losing voters. On such close votes, it is [b]strongly recommended[/b] that the proposer take steps to address any concerns that were raised and re-submit.

5
doc/project/toc.html
View File

@ -1,5 +0,0 @@
<h3>Project Information</h3>
<ul>
<li><a href="help/project/governance">Project Governance</a></li>
<li><a href="help/project/versions">Versions and Versioning</a></li>
</ul>

30
doc/project/versions.bb
View File

@ -1,30 +0,0 @@
[h2]Versions and Releases[/h2]
$Projectname currently uses a standard version numbering sequence of $x.$y(.$z), for instance '1.12' or '1.12.1'. The first digit is the major version number. Major versions are released "roughly" once per year; often in December.
The second digit is the minor release number. If this number is odd, it is a development version. If the number is even, it is a released version. Minor versions are released (moved from dev to master) typically once per month when development is 'stable', but this is likely to increase. Going forward minor releases will be made somewhere between one and three months; corresponding to a stable code point and when there is general community consensus that the current code base is stable enough to consider a release.
The final digit is an interface or patch designator.
The release process involves changing the version number (by definition the minor version number will be odd, and the minor number will be incremented). Once a year for a major release the major version will be incremented, and the minor number reset to 0.
The release candidate is moved to a new branch; and testing will commence/continue for a period of 1-2 weeks afterward or until any significant issues have been resolved. This branch is usually labelled with RC (release candidate); for instance 1.8RC represents the pending release of version 1.8. At this time, the minor version number on the dev branch is incremented to the next odd number. (For instance 1.9). New development can then take place in the dev branch.
Bug fixes should always be applied to 'dev' and from there merged forward (typically with git cherry-pick) to the RC branch and if necessary applied to the master or official release branch.
At the time a release candidate is produced, the language strings file is frozen until a release is made. Translation work may continue, but all translations should be submitted to 'dev' and merged forward to RC.
Once RC testing is completed, RC is merged to 'master' and the RC version designator removed; resulting in one final checkin to change the version number. The CHANGELOG file should also be updated at or just prior to this time. If there are merge conflicts during this final merge, the merge will be abandoned; and 'git merge -s ours' applied. This results in a replacement of master with the contents of the RC branch. Conflicts often arise with string updates which were made to master after the last release and cannot easily be resolved without hand editing. Since this is a release of tested code, hand editing is discouraged, and the replacement merge strategy should be used instead. It is assumed that RC now contains the most recent well-tested code.
Once the release is live and merged to master, the RC branch may be removed.
Fixes may be made to master after release. Where possible these should be made to dev and 'git cherry-pick' used to merge forward; which preserves the commit info and prevents merge conflicts in the next cycle. Only rarely does a patch only apply to the master branch. If necessary this can be made. If the change is severe, the interface version number should be incremented. This is at the discretion of the community. In any event, a 'git pull' of the master branch should always result in the latest release with any post-release patches applied.
The interface number (the $z in $x.$y.$z) should be incremented in dev whenever a change is made which changes the interfaces or API in incompatible ways so that any external packages (especially addons and API clients) relying on a the current behaviour can discover and change their own interfaces accordingly at the point that it changed.

2
doc/toc.html
View File

@ -37,6 +37,7 @@
<ul class="list-group"> <ul class="list-group">
<li class="doco-list-group-item"><a href="/help/admin/administrator_guide">Guide</a></li> <li class="doco-list-group-item"><a href="/help/admin/administrator_guide">Guide</a></li>
<li class="doco-list-group-item"><a href="/help/admin/hub_snapshots">Hub Snapshots</a></li> <li class="doco-list-group-item"><a href="/help/admin/hub_snapshots">Hub Snapshots</a></li>
<li class="doco-list-group-item"><a href="/help/database">Database Tables</a></li>
</ul> </ul>
</div> </div>
</div> </div>
@ -52,6 +53,7 @@
<li class="doco-list-group-item"><a href="/help/developer/covenant">Code of Conduct</a></li> <li class="doco-list-group-item"><a href="/help/developer/covenant">Code of Conduct</a></li>
<li class="doco-list-group-item"><a href="/help/developer/zot_protocol">Zot Protocol</a></li> <li class="doco-list-group-item"><a href="/help/developer/zot_protocol">Zot Protocol</a></li>
<li class="doco-list-group-item"><a href="/help/developer/api_zot">Zot API</a></li> <li class="doco-list-group-item"><a href="/help/developer/api_zot">Zot API</a></li>
<li class="doco-list-group-item"><a href="/help/hooklist">Hooks</a></li>
</ul> </ul>
</div> </div>
</div> </div>