Currently, I use the semantic versioning for an API.
Versioning is envolves like this:
MAJOR version when you make incompatible API changes
MINOR version when you add functionality in a backwards compatible manner
PATCH version when you make backwards compatible bug fixes
Should I increment the PATCH, if I only update the documentation (swagger, internal documenation, YAML, ...) to add example, or correct a description attach to the API?
Thanks for your help ;)
Should I increment the PATCH, if I only update the documentation (swagger, internal documenation, YAML, ...) to add example, or correct a description attach to the API?
Depends on the example/correction. Does it represent a break from previous understanding of the use of your API's? Here's a very contrived example for discussion:
API: int plus(int a, int b)
Documentation: int plus(int a, int b) sums a + b.
The above was released as 1.0.0, then someone reviews the code and points out that on overflow, the function returns 0.
Updated documentation: int plus(int a, int b) sums a + b where a < 32767 and b < 32767, otherwise, returns 0.
So, whether this is a breaking change, depends on the language and its behavior when a + b overflow. Some languages throw an exception or segfault, others, it's common for them to simply return a modulo result of some kind. Let's say it's C, in that case, this documentation change is likely a breaking change (well, probably most programming languages actually).
The point here is that initial documentation is often not much better than a superficial restatement of the API itself. Subsequent complaints (bug reports) from customers, often drive the next round of documentation changes, when the customers are surprised by the results. So yes, even though the original intent of the developer hasn't changed, the documentation does represent a breaking change in regard to the expected results.
Had the documentation been changed to match exactly what the customers expected/witnessed in use, then no, it's not a breaking change.
The documentation is part of the feature set. Back-filling missing documentation is usually a feature addition, so you'd bump the minor version. A minor correction would be a patch.
Related
Say I have written a piece of software (in R, for didactic purposes) which is following the Semantic Versioning Specification. This is the content of version 1.0.0 of the software:
funk <- function(x) {
jitter(x)
}
Which works so that
set.seed(1)
print(funk(0))
yields
[1] -0.009379653
Now suppose I change my function to this:
funk <- function(x) {
unrelated_random_stuff <- sample(1:10)
jitter(x)
}
And now, set.seed(1); print(funk(0)) yields
[1] -0.01176102
According to SemVer, does this constitute a major change? I.e., if I publish the software with these changes, should it be 2.0.0? I'm inclined to think so, since this technically changes results from scripts based on version 1.0.0, but I am not sure this qualifies as "breaking backwards compatibility" since we're talking about randomly-generated numbers.
If your customers are inclined to take a dependency on the output value, then yes, you probably want to bump the major version number. Even if this is library code, it's possible someone is using it for fuzz testing and it's critically important to yield reproducible result, in order to find track down and fix bugs, as well as ensure the fix does not regress in the future.
I am implementing an algorithm using Data.Ratio (convergents of continued fractions).
However, I encounter two obstacles:
The algorithm starts with the fraction 1%0 - but this throws a zero denominator exception.
I would like to pattern match the constructor a :% b
I was exploring on hackage. An in particular the source seems to be using exactly these features (e.g. defining infinity = 1 :% 0, or pattern matching for numerator).
As beginner, I am also confused where it is determined that (%), numerator and such are exposed to me, but not infinity and (:%).
I have already made a dirty workaround using a tuple of integers, but it seems silly to reinvent the wheel about something so trivial.
Also would be nice to learn how read the source which functions are exposed.
They aren't exported precisely to prevent people from doing stuff like this. See, the type
data Ratio a = a:%a
contains too many values. In particular, e.g. 2/6 and 3/9 are actually the same number in ℚ and both represented by 1:%3. Thus, 2:%6 is in fact an illegal value, and so is, sure enough, 1:%0. Or it might be legal but all functions know how to treat them so 2:%6 is for all observable means equal to 1:%3 – I don't in fact know which of these options GHC chooses, but at any rate it's an implementation detail and could change in future releases without notice.
If the library authors themselves use such values for e.g. optimisation tricks that's one thing – they have after all full control over any algorithmic details and any undefined behaviour that could arise. But if users got to construct such values, it would result in brittle code.
So – if you find yourself starting an algorithm with 1/0, then you should indeed not use Ratio at all there but simply store numerator and denominator in a plain tuple, which has no such issues, and only make the final result a Ratio with %.
I am using python's MIP module for optimization. I have set up a model with few parameters. I would want to limit the number of solutions and add stop timer if I don't find any solution in given time. I have added these parameters as given below:
m = Model(name='opt', sense=MAXIMIZE, solver_name=CBC)
m.optimize(max_solutions=1, max_seconds= 300)
somehow none of them seem working to me. it does not even stop looking for a solution after given time and it returns 2 solution sometimes even if I want to limit it to 1. Is there something I am missing in syntax?
One more thing, Gurobi has an option to add multiple variable using add_Vars parameter. Is there anything similar available in MIP too?
Thanks.
Yeah I have been doing some tests myself (with the Python-MIP solver) and seen some similar issues. Apparently it's still quite new and many improvements have been implemented recently or are yet to be developed. I will post from what I've learned:
regarding max_seconds: There's been at least one (closed) issue on the official repo related to using max_seconds parameter and CBC.
regarding max_solutions: If you are using version 1.6.2 or before, here's an explanation for that: until 1.6.1, the m.optimize(max_solutions=1) wasn't setting the maximum solution parameter to CBC. In that case you should try with the following lines (or just update to current version):
m.max_solutions = 1
m.optimize()
If the former don't help for the max_seconds and max_solutions parameters, I guess you'd better post your question as an issue at the library's repo to get answers and support from the project contributors.
Adding multiple variables, similar to gurobipy's Model.addVars() method: Yes, you can do it as follows
p = {(i, j): m.add_var(var_type=CONTINUOUS, lb=0, name="p[%d,%d]" % (i, j))
for i in Set_i for j in Set_j}
In this example, we are adding a variable p_ij and specifying it's continuous
(vs. binary or integer), has lower bound 0, and the sets where the indexes run. Set_i and Set_j are Python lists. See the documentation here for a more detailed explanation on how to use it. Similarly, you can create indexed constraints using the add_constr method, similar to Gurobi's Model.AddConstrs() method.
This question is related to string algorithm, not version control tools or management tools.
I learnt the diff algorithm and tried to implement one. That is, given string A and string B, the diff calculate a sequence of actions that can convert A into B.
I wonder, if it possible, given a string S, and a sequence of actions that diff algorithm can produce, the algorithm will tell if the string S is (a) the origin string A, (b) the patched string B, (c) unrelated string. And what if S is only one of A and B.
Actuallly, what I'm really doing is researching a method that can tell if a patch have been applied (source code level or binary code level). I tried google some time, but didn't find something useful.
It's pretty complicated, but it can be done, on some level.
Essentially, you parse the source level into tokens, after that, you build the abstract syntax tree. Once that is done, you must build a diff tool that can do semantic differential analysis between abstract syntax trees. SemanticMerge for example, does that.
Once that is done, you have semantical difference between two source codes, and then you need to define what exactly consists of a patch.
Some of the rules can be:
1) Variable content was changed
2) A if check was added
The bottom line is, differenting between patch and new functionality is not an easy task. The most reliable way is to probably check the binary file version numbers, and understand the versioning schema.
Eg, only minor version is updated, if patches are applied.
can two use cases extend or include each other at the same time?
A extend/include B and B extend/include A
I'm pretty sure the answer is "NO".
You've just described the digital equivalent fo the chicken and egg problem.
Circular references are [almost] always Bad Things (tm). The only place I know it to not be horrible is in the context of a linked list, in which each entry has a pointer to another of its own type.
If (A includes/extends B and B includes/extends A) then A = B
Admitting that if A extends/includes B then A >= B
It seems likely not, though I'm sure you could do it if you went generic [and useless] enough. Do you have a specific example? There are always exemptions to the rules and I'd be curious to see one.
below is the senario for business use case (business modelling) not system use case:
USE Case A: Service Vehicle
Use Case B: Authorise Additional repair
Use Case C: Repair Vehicle
Additional repair could be identified during initial repair.
or repair could be identified as a new repair during service,
in both case, customer authorisation is required?
A extend B and B extend C (authorisation and start of repair identified during service)
C extend B (authorisation for additional repair identified during repair)
It's rare but in the general case, there's nothing that prevents use cases from including/using each other.
the answer is no. extend and include are mutually-exclusive relationship types. Most likely the use-cases are incorrectly factored/separated, or you've misunderstood the extend/include relationship definitions, or both.
given the example you posted (fyi it is better for you to edit the question rather than post an answer that does not answer the original question) i would venture that B extends A and B extends C, since in both cases A and C additional repairs (case B) may be identified.
alternately, use cases A and C could conditionally include use case B
offhand, i would model this as Work On Vehicle, which is a composition of 2 use-cases, Obtain Customer Authorization, and Service Vehicle, where the latter includes any kind of service or repair and requires the output of the former before starting the work. The notion of 'additional repairs' is just another instance of Work On Vehicle.
but i don't know the full business context, so your mileage may vary ;-)
EDIT: you wrote "but in this case: work is being carried out and further authorisation is required during the course of work", but i don't see how that really matters.
the first step is to eliminate the confusion about includes and extends. Try modeling each use-case completely and independently, and then look at what is common to see if includes/extends is warranted
"YES" - Checked the Spec.
I just read through the UML specification section for use cases:
http://www.omg.org/spec/UML/2.1.2/Superstructure/PDF/
There was no rule that would prevent doing this that I could find. Many people may conceptually have a problem with this, but that is ok, as you are just instinctively trying to objectize or structure use cases logically. Use Cases are a behavior (or set) and are not like classes/"objects". We are not talking about Java objects.
Even in Rational Software Modeler (IBM) allows this "circular reference".
In practice and in trying to map this to Java or other Object languages it may not make sense or get confusing.