Mercurial > p > roundup > code
comparison doc/reference.txt @ 7359:3a98a81c6e57
Reorg multiple sections
consolidate what you can/can't do to the schema into one section and
move to the top of the Tracker Schema section.. Also outline how you
*can* change the type of a property.
In the "Classes and Properties - creating a new information store
section", add new Method subsection after Properties subsection. Place
all 4 method sections in there moving them from below.
Move IssueClass section before FileClass section because IssueClass
incorporates links to FileClass not the other way around.
Fix indexes.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Tue, 16 May 2023 02:33:39 -0400 |
| parents | 0cb4541bad71 |
| children | 23abe048d1de |
comparison
equal
deleted
inserted
replaced
| 7358:79fd1bf20543 | 7359:3a98a81c6e57 |
|---|---|
| 658 | 658 |
| 659 A tracker schema defines what data is stored in the tracker's database. | 659 A tracker schema defines what data is stored in the tracker's database. |
| 660 Schemas are defined using Python code in the ``schema.py`` module of your | 660 Schemas are defined using Python code in the ``schema.py`` module of your |
| 661 tracker. | 661 tracker. |
| 662 | 662 |
| 663 What you can/can't do to the schema | |
| 664 ----------------------------------- | |
| 665 | |
| 666 Your schema may be changed at any time before or after the tracker has been | |
| 667 initialised (or used). You may: | |
| 668 | |
| 669 **Add new properties to classes, or add whole new classes** | |
| 670 This is painless and easy to do - there are generally no repercussions | |
| 671 from adding new information to a tracker's schema. | |
| 672 | |
| 673 **Remove properties** | |
| 674 Removing properties is a little more tricky - you need to make sure that | |
| 675 the property is no longer used in the `web interface`_ *or* by the | |
| 676 detectors_. | |
| 677 | |
| 678 You must never: | |
| 679 | |
| 680 **Remove the user class** | |
| 681 This class is the only *required* class in Roundup. | |
| 682 | |
| 683 **Remove the "username", "address", "password" or "realname" user properties** | |
| 684 Various parts of Roundup require these properties. Don't remove them. | |
| 685 | |
| 686 **Change the type of a property** | |
| 687 Property types must *never* [1]_ be changed - the database simply | |
| 688 doesn't take this kind of action into account. Note that you can't | |
| 689 just remove a property and re-add it as a new type either. If you | |
| 690 wanted to make the assignedto property a Multilink, you'd need to | |
| 691 create a new property assignedto_list and remove the old assignedto | |
| 692 property. | |
| 693 | |
| 694 .. [1] If you shut down the tracker, `export the database`_, modify the | |
| 695 exported csv property data to be compatible with the new type, | |
| 696 change the property type in the schema, and finally import the | |
| 697 changed exported data, you can change the property type. It is | |
| 698 not trivial nor for the faint of heart. But it can be done. | |
| 699 | |
| 700 .. _export the database: admin_guide.html#using-roundup-admin | |
| 701 | |
| 663 The ``schema.py`` and ``initial_data.py`` modules | 702 The ``schema.py`` and ``initial_data.py`` modules |
| 664 ------------------------------------------------- | 703 ------------------------------------------------- |
| 665 | 704 |
| 666 The schema.py module is used to define what your tracker looks like | 705 The schema.py module is used to define what your tracker looks like |
| 667 on the inside, the schema of the tracker. It defines the Classes | 706 on the inside, the schema of the tracker. It defines the Classes |
| 709 status=Link("status"), assignedto=Link("user"), | 748 status=Link("status"), assignedto=Link("user"), |
| 710 priority=Link("priority")) | 749 priority=Link("priority")) |
| 711 issue.setkey('title') | 750 issue.setkey('title') |
| 712 | 751 |
| 713 .. index:: schema; allowed changes | 752 .. index:: schema; allowed changes |
| 714 | |
| 715 What you can't do to the schema | |
| 716 ------------------------------- | |
| 717 | |
| 718 You must never: | |
| 719 | |
| 720 **Remove the user class** | |
| 721 This class is the only *required* class in Roundup. | |
| 722 | |
| 723 **Remove the "username", "address", "password" or "realname" user properties** | |
| 724 Various parts of Roundup require these properties. Don't remove them. | |
| 725 | |
| 726 **Change the type of a property** | |
| 727 Property types must *never* be changed - the database simply doesn't take | |
| 728 this kind of action into account. Note that you can't just remove a | |
| 729 property and re-add it as a new type either. If you wanted to make the | |
| 730 assignedto property a Multilink, you'd need to create a new property | |
| 731 assignedto_list and remove the old assignedto property. | |
| 732 | |
| 733 | |
| 734 What you can do to the schema | |
| 735 ----------------------------- | |
| 736 | |
| 737 Your schema may be changed at any time before or after the tracker has been | |
| 738 initialised (or used). You may: | |
| 739 | |
| 740 **Add new properties to classes, or add whole new classes** | |
| 741 This is painless and easy to do - there are generally no repercussions | |
| 742 from adding new information to a tracker's schema. | |
| 743 | |
| 744 **Remove properties** | |
| 745 Removing properties is a little more tricky - you need to make sure that | |
| 746 the property is no longer used in the `web interface`_ *or* by the | |
| 747 detectors_. | |
| 748 | |
| 749 | |
| 750 | 753 |
| 751 Classes and Properties - creating a new information store | 754 Classes and Properties - creating a new information store |
| 752 --------------------------------------------------------- | 755 --------------------------------------------------------- |
| 753 | 756 |
| 754 In the tracker above, we've defined 7 classes of information: | 757 In the tracker above, we've defined 7 classes of information: |
| 1036 Link to the user that last modified the item. | 1039 Link to the user that last modified the item. |
| 1037 *activity* | 1040 *activity* |
| 1038 Date the item was last modified. | 1041 Date the item was last modified. |
| 1039 | 1042 |
| 1040 | 1043 |
| 1044 .. index:: double: schema; class methods | |
| 1045 | |
| 1046 Methods | |
| 1047 ~~~~~~~ | |
| 1048 | |
| 1049 All classes have the following methods. | |
| 1050 | |
| 1051 .. index:: triple: schema; class method; setkey | |
| 1052 | |
| 1053 setkey(property) | |
| 1054 :::::::::::::::: | |
| 1055 | |
| 1056 .. index:: roundup-admin; setting assignedto on an issue | |
| 1057 | |
| 1058 Select a String property of the class to be the key property. The key | |
| 1059 property must be unique, and allows references to the items in the class | |
| 1060 by the content of the key property. That is, we can refer to users by | |
| 1061 their username: for example, let's say that there's an issue in Roundup, | |
| 1062 issue 23. There's also a user, richard, who happens to be user 2. To | |
| 1063 assign an issue to him, we could do either of:: | |
| 1064 | |
| 1065 roundup-admin set issue23 assignedto=2 | |
| 1066 | |
| 1067 or:: | |
| 1068 | |
| 1069 roundup-admin set issue23 assignedto=richard | |
| 1070 | |
| 1071 Note, the same thing can be done in the web and e-mail interfaces. | |
| 1072 | |
| 1073 .. index:: triple: schema; class method; setlabelprop | |
| 1074 | |
| 1075 setlabelprop(property) | |
| 1076 :::::::::::::::::::::: | |
| 1077 | |
| 1078 Select a property of the class to be the label property. The label | |
| 1079 property is used whereever an item should be uniquely identified, e.g., | |
| 1080 when displaying a link to an item. If setlabelprop is not specified for | |
| 1081 a class, the following values are tried for the label: | |
| 1082 | |
| 1083 * the key of the class (see the `setkey(property)`_ section above) | |
| 1084 * the "name" property | |
| 1085 * the "title" property | |
| 1086 * the first property from the sorted property name list | |
| 1087 | |
| 1088 So in most cases you can get away without specifying setlabelprop | |
| 1089 explicitly. | |
| 1090 | |
| 1091 You should make sure that users have View access to this property or | |
| 1092 the id property for a class. If the property can not be viewed by a | |
| 1093 user, looping over items in the class (e.g. messages attached to an | |
| 1094 issue) will not work. | |
| 1095 | |
| 1096 .. index:: triple: schema; class method; setorderprop | |
| 1097 | |
| 1098 setorderprop(property) | |
| 1099 :::::::::::::::::::::: | |
| 1100 | |
| 1101 Select a property of the class to be the order property. The order | |
| 1102 property is used whenever using a default sort order for the class, | |
| 1103 e.g., when grouping or sorting class A by a link to class B in the user | |
| 1104 interface, the order property of class B is used for sorting. If | |
| 1105 setorderprop is not specified for a class, the following values are tried | |
| 1106 for the order property: | |
| 1107 | |
| 1108 * the property named "order" | |
| 1109 * the label property (see `setlabelprop(property)`_ above) | |
| 1110 | |
| 1111 So in most cases you can get away without specifying setorderprop | |
| 1112 explicitly. | |
| 1113 | |
| 1114 .. index:: triple: schema; class method; create | |
| 1115 | |
| 1116 create(information) | |
| 1117 ::::::::::::::::::: | |
| 1118 | |
| 1119 Create an item in the database. This is generally used to create items | |
| 1120 in the "definitional" classes like "priority" and "status". | |
| 1121 | |
| 1122 IssueClass | |
| 1123 ~~~~~~~~~~ | |
| 1124 | |
| 1125 IssueClasses automatically include the "messages", "files", "nosy", and | |
| 1126 "superseder" properties. | |
| 1127 | |
| 1128 The messages and files properties list the links to the messages and | |
| 1129 files related to the issue. The nosy property is a list of links to | |
| 1130 users who wish to be informed of changes to the issue - they get "CC'ed" | |
| 1131 e-mails when messages are sent to or generated by the issue. The nosy | |
| 1132 reactor (in the ``'detectors'`` directory) handles this action. The | |
| 1133 superseder link indicates an issue which has superseded this one. | |
| 1134 | |
| 1135 They also have the dynamically generated "creation", "activity" and | |
| 1136 "creator" properties. | |
| 1137 | |
| 1138 The value of the "creation" property is the date when an item was | |
| 1139 created, and the value of the "activity" property is the date when any | |
| 1140 property on the item was last edited (equivalently, these are the dates | |
| 1141 on the first and last records in the item's journal). The "creator" | |
| 1142 property holds a link to the user that created the issue. | |
| 1143 | |
| 1041 .. index:: triple: schema; class property; content | 1144 .. index:: triple: schema; class property; content |
| 1042 triple: schema; class property; type | 1145 triple: schema; class property; type |
| 1043 | 1146 |
| 1044 FileClass | 1147 FileClass |
| 1045 ~~~~~~~~~ | 1148 ~~~~~~~~~ |
| 1127 .. index:: triple: schema; class property; messages | 1230 .. index:: triple: schema; class property; messages |
| 1128 triple: schema; class property; files | 1231 triple: schema; class property; files |
| 1129 triple: schema; class property; nosy | 1232 triple: schema; class property; nosy |
| 1130 triple: schema; class property; superseder | 1233 triple: schema; class property; superseder |
| 1131 | 1234 |
| 1132 IssueClass | 1235 .. index:: schema; item ordering |
| 1133 ~~~~~~~~~~ | |
| 1134 | |
| 1135 IssueClasses automatically include the "messages", "files", "nosy", and | |
| 1136 "superseder" properties. | |
| 1137 | |
| 1138 The messages and files properties list the links to the messages and | |
| 1139 files related to the issue. The nosy property is a list of links to | |
| 1140 users who wish to be informed of changes to the issue - they get "CC'ed" | |
| 1141 e-mails when messages are sent to or generated by the issue. The nosy | |
| 1142 reactor (in the ``'detectors'`` directory) handles this action. The | |
| 1143 superseder link indicates an issue which has superseded this one. | |
| 1144 | |
| 1145 They also have the dynamically generated "creation", "activity" and | |
| 1146 "creator" properties. | |
| 1147 | |
| 1148 The value of the "creation" property is the date when an item was | |
| 1149 created, and the value of the "activity" property is the date when any | |
| 1150 property on the item was last edited (equivalently, these are the dates | |
| 1151 on the first and last records in the item's journal). The "creator" | |
| 1152 property holds a link to the user that created the issue. | |
| 1153 | |
| 1154 .. index: triple: schema; class method; setkey | |
| 1155 | |
| 1156 setkey(property) | |
| 1157 ~~~~~~~~~~~~~~~~ | |
| 1158 | |
| 1159 .. index:: roundup-admin; setting assignedto on an issue | |
| 1160 | |
| 1161 Select a String property of the class to be the key property. The key | |
| 1162 property must be unique, and allows references to the items in the class | |
| 1163 by the content of the key property. That is, we can refer to users by | |
| 1164 their username: for example, let's say that there's an issue in Roundup, | |
| 1165 issue 23. There's also a user, richard, who happens to be user 2. To | |
| 1166 assign an issue to him, we could do either of:: | |
| 1167 | |
| 1168 roundup-admin set issue23 assignedto=2 | |
| 1169 | |
| 1170 or:: | |
| 1171 | |
| 1172 roundup-admin set issue23 assignedto=richard | |
| 1173 | |
| 1174 Note, the same thing can be done in the web and e-mail interfaces. | |
| 1175 | |
| 1176 .. index: triple: schema; class method; setlabelprop | |
| 1177 | |
| 1178 setlabelprop(property) | |
| 1179 ~~~~~~~~~~~~~~~~~~~~~~ | |
| 1180 | |
| 1181 Select a property of the class to be the label property. The label | |
| 1182 property is used whereever an item should be uniquely identified, e.g., | |
| 1183 when displaying a link to an item. If setlabelprop is not specified for | |
| 1184 a class, the following values are tried for the label: | |
| 1185 | |
| 1186 * the key of the class (see the `setkey(property)`_ section above) | |
| 1187 * the "name" property | |
| 1188 * the "title" property | |
| 1189 * the first property from the sorted property name list | |
| 1190 | |
| 1191 So in most cases you can get away without specifying setlabelprop | |
| 1192 explicitly. | |
| 1193 | |
| 1194 You should make sure that users have View access to this property or | |
| 1195 the id property for a class. If the property can not be viewed by a | |
| 1196 user, looping over items in the class (e.g. messages attached to an | |
| 1197 issue) will not work. | |
| 1198 | |
| 1199 .. index: triple: schema; class method; setorderprop | |
| 1200 | |
| 1201 setorderprop(property) | |
| 1202 ~~~~~~~~~~~~~~~~~~~~~~ | |
| 1203 | |
| 1204 Select a property of the class to be the order property. The order | |
| 1205 property is used whenever using a default sort order for the class, | |
| 1206 e.g., when grouping or sorting class A by a link to class B in the user | |
| 1207 interface, the order property of class B is used for sorting. If | |
| 1208 setorderprop is not specified for a class, the following values are tried | |
| 1209 for the order property: | |
| 1210 | |
| 1211 * the property named "order" | |
| 1212 * the label property (see `setlabelprop(property)`_ above) | |
| 1213 | |
| 1214 So in most cases you can get away without specifying setorderprop | |
| 1215 explicitly. | |
| 1216 | |
| 1217 .. index: triple: schema; class method; create | |
| 1218 | |
| 1219 create(information) | |
| 1220 ~~~~~~~~~~~~~~~~~~~ | |
| 1221 | |
| 1222 Create an item in the database. This is generally used to create items | |
| 1223 in the "definitional" classes like "priority" and "status". | |
| 1224 | |
| 1225 .. index: schema; item ordering | |
| 1226 | 1236 |
| 1227 A note about ordering | 1237 A note about ordering |
| 1228 ~~~~~~~~~~~~~~~~~~~~~ | 1238 ~~~~~~~~~~~~~~~~~~~~~ |
| 1229 | 1239 |
| 1230 When we sort items in the hyperdb, we use one of a number of methods, | 1240 When we sort items in the hyperdb, we use one of a number of methods, |