1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2017, Tooru Oonuma.
# This file is distributed under the same license as the python-pcl package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: python-pcl 0.0.1.dev0\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2017-07-31 13:25+0900\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#: ..\..\source\compatibility.rst:2
msgid "API Compatibility Policy"
msgstr ""
#: ..\..\source\compatibility.rst:4
msgid "This document expresses the design policy on compatibilities of python-pcl APIs. Development team should obey this policy on deciding to add, extend, and change APIs and their behaviors."
msgstr ""
#: ..\..\source\compatibility.rst:7
msgid "This document is written for both users and developers. Users can decide the level of dependencies on python-pcl implementations in their codes based on this document. Developers should read through this document before creating pull requests that contain changes on the interface. Note that this document may contain ambiguities on the level of supported compatibilities."
msgstr ""
#: ..\..\source\compatibility.rst:14
msgid "Versioning and Backward Compatibilities"
msgstr ""
#: ..\..\source\compatibility.rst:16
msgid "The updates of python-pcl are classified into three levels: major, minor, and revision. These types have distinct levels of backward compatibilities."
msgstr ""
#: ..\..\source\compatibility.rst:19
msgid "**Major update** contains disruptive changes that break the backward compatibility."
msgstr ""
#: ..\..\source\compatibility.rst:20
msgid "**Minor update** contains addition and extension to the APIs keeping the supported backward compatibility."
msgstr ""
#: ..\..\source\compatibility.rst:21
msgid "**Revision update** contains improvements on the API implementations without changing any API specifications."
msgstr ""
#: ..\..\source\compatibility.rst:23
msgid "Note that we do not support full backward compatibility, which is almost infeasible for Python-based APIs, since there is no way to completely hide the implementation details."
msgstr ""
#: ..\..\source\compatibility.rst:27
msgid "Processes to Break Backward Compatibilities"
msgstr ""
#: ..\..\source\compatibility.rst:30
msgid "Deprecation, Dropping, and Its Preparation"
msgstr ""
#: ..\..\source\compatibility.rst:32
msgid "Any APIs may be *deprecated* at some minor updates. In such a case, the deprecation note is added to the API documentation, and the API implementation is changed to fire deprecation warning (if possible). There should be another way to reimplement the same things previously written with the deprecated APIs."
msgstr ""
#: ..\..\source\compatibility.rst:36
msgid "Any APIs may be marked as *to be dropped in the future*. In such a case, the dropping is stated in the documentation with the major version number on which the API is planned to be dropped, and the API implementation is changed to fire the future warning (if possible)."
msgstr ""
#: ..\..\source\compatibility.rst:39
msgid "The actual dropping should be done through the following steps:"
msgstr ""
#: ..\..\source\compatibility.rst:41
msgid "Make the API deprecated. At this point, users should not need the deprecated API in their new application codes."
msgstr ""
#: ..\..\source\compatibility.rst:43
msgid "After that, mark the API as *to be dropped in the future*. It must be done in the minor update different from that of the deprecation."
msgstr ""
#: ..\..\source\compatibility.rst:45
msgid "At the major version announced in the above update, drop the API."
msgstr ""
#: ..\..\source\compatibility.rst:47
msgid "Consequently, it takes at least two minor versions to drop any APIs after the first deprecation."
msgstr ""
#: ..\..\source\compatibility.rst:50
msgid "API Changes and Its Preparation"
msgstr ""
#: ..\..\source\compatibility.rst:52
msgid "Any APIs may be marked as *to be changed in the future* for changes without backward compatibility. In such a case, the change is stated in the documentation with the version number on which the API is planned to be changed, and the API implementation is changed to fire the future warning on the certain usages."
msgstr ""
#: ..\..\source\compatibility.rst:55
msgid "The actual change should be done in the following steps:"
msgstr ""
#: ..\..\source\compatibility.rst:57
msgid "Announce that the API will be changed in the future. At this point, the actual version of change need not be accurate."
msgstr ""
#: ..\..\source\compatibility.rst:59
msgid "After the announcement, mark the API as *to be changed in the future* with version number of planned changes. At this point, users should not use the marked API in their new application codes."
msgstr ""
#: ..\..\source\compatibility.rst:61
msgid "At the major update announced in the above update, change the API."
msgstr ""
#: ..\..\source\compatibility.rst:65
msgid "Supported Backward Compatibility"
msgstr ""
#: ..\..\source\compatibility.rst:67
msgid "This section defines backward compatibilities that minor updates must maintain."
msgstr ""
#: ..\..\source\compatibility.rst:70
msgid "Documented Interface"
msgstr ""
#: ..\..\source\compatibility.rst:72
msgid "python-pcl has the official API documentation. Many applications can be written based on the documented features. We support backward compatibilities of documented features. In other words, codes only based on the documented features run correctly with minor/revision-updated versions."
msgstr ""
#: ..\..\source\compatibility.rst:77
msgid "Developers are encouraged to use apparent names for objects of implementation details. For example, attributes outside of the documented APIs should have one or more underscores at the prefix of their names."
msgstr ""
#: ..\..\source\compatibility.rst:83
msgid "Undocumented behaviors"
msgstr ""
#: ..\..\source\compatibility.rst:85
msgid "Behaviors of python-pcl implementation not stated in the documentation are undefined. Undocumented behaviors are not guaranteed to be stable between different minor/revision versions."
msgstr ""
#: ..\..\source\compatibility.rst:88
msgid "Minor update may contain changes to undocumented behaviors. For example, suppose an API X is added at the minor update. In the previous version, attempts to use X cause AttributeError. This behavior is not stated in the documentation, so this is undefined. Thus, adding the API X in minor version is permissible."
msgstr ""
#: ..\..\source\compatibility.rst:94
msgid "Revision update may also contain changes to undefined behaviors. Typical example is a bug fix. Another example is an improvement on implementation, which may change the internal object structures not shown in the documentation. As a consequence, **even revision updates do not support compatibility of pickling, unless the full layout of pickled objects is clearly documented.**"
msgstr ""
#: ..\..\source\compatibility.rst:100
msgid "Documentation Error"
msgstr ""
#: ..\..\source\compatibility.rst:102
msgid "Compatibility is basically determined based on the documentation, though it sometimes contains errors. It may make the APIs confusing to assume the documentation always stronger than the implementations. We therefore may fix the documentation errors in any updates that may break the compatibility in regard to the documentation."
msgstr ""
#: ..\..\source\compatibility.rst:107
msgid "Developers MUST NOT fix the documentation and implementation of the same functionality at the same time in revision updates as \"bug fix\". Such a change completely breaks the backward compatibility. If you want to fix the bugs in both sides, first fix the documentation to fit it into the implementation, and start the API changing procedure described above."
msgstr ""
#: ..\..\source\compatibility.rst:112
msgid "Object Attributes and Properties"
msgstr ""
#: ..\..\source\compatibility.rst:114
msgid "Object attributes and properties are sometimes replaced by each other at minor updates. It does not break the user codes, except the codes depend on how the attributes and properties are implemented."
msgstr ""
#: ..\..\source\compatibility.rst:118
msgid "Functions and Methods"
msgstr ""
#: ..\..\source\compatibility.rst:120
msgid "Methods may be replaced by callable attributes keeping the compatibility of parameters and return values in minor updates. It does not break the user codes, except the codes depend on how the methods and callable attributes are implemented."
msgstr ""
#: ..\..\source\compatibility.rst:124
msgid "Exceptions and Warnings"
msgstr ""
#: ..\..\source\compatibility.rst:126
msgid "The specifications of raising exceptions are considered as a part of standard backward compatibilities. No exception is raised in the future versions with correct usages that the documentation allows, unless the API changing process is completed."
msgstr ""
#: ..\..\source\compatibility.rst:129
msgid "On the other hand, warnings may be added at any minor updates for any APIs. It means minor updates do not keep backward compatibility of warnings."
msgstr ""
#: ..\..\source\compatibility.rst:134
msgid "Installation Compatibility"
msgstr ""
#: ..\..\source\compatibility.rst:136
msgid "The installation process is another concern of compatibilities. We support environmental compatibilities in the following ways."
msgstr ""
#: ..\..\source\compatibility.rst:139
msgid "Any changes of dependent libraries that force modifications on the existing environments must be done in major updates. Such changes include following cases:"
msgstr ""
#: ..\..\source\compatibility.rst:142
msgid "dropping supported versions of dependent libraries (e.g. dropping cuDNN v2)"
msgstr ""
#: ..\..\source\compatibility.rst:143
msgid "adding new mandatory dependencies (e.g. adding h5py to setup_requires)"
msgstr ""
#: ..\..\source\compatibility.rst:145
msgid "Supporting optional packages/libraries may be done in minor updates (e.g. supporting h5py in optional features)."
msgstr ""
#: ..\..\source\compatibility.rst:148
msgid "The installation compatibility does not guarantee that all the features of python-pcl correctly run on supported environments. It may contain bugs that only occurs in certain environments. Such bugs should be fixed in some updates."
msgstr ""
|
