I'm learning about how to assign and increment version numbers with the rule called "Semantic Versioning" from http://semver.org/.
Among all its rules, the first one said:
Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it should be precise and comprehensive"
I am confused about "public API". What does it refer to?
Public API refers to the "point of access" that the external world (users, other programs and/or programmers, etc) have to your software.
E.g., if you're developing a library, the public API is the set of all the methods invokations that can be made to your library.
There is understanding that, unless a major version changes, your API will be backwards-compatible, i.e. all the calls that were valid on a version will be valid on a later version.
You can read at point 9 of those rules:
Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.
I discovered SemVer today and read up on it from several sources to ensure I had fully grasped it.
I am confused about "public API". What does it refer to?
I was also confused about this. I wanted to set about using SemVer immediately to version some of my scripts, but they didn't have a public API and it wasn't even clear to me how they could have one.
The best answer I found is one that explains:
SemVer is explicitly not for versioning all code. It's only for code that has a public API.
Using SemVer to version the wrong software is an all too common source
of frustration. SemVer can't version software that doesn't declare a
public API.
Software that declare a public API include libraries and command line
applications. Software that don't declare a public API include many
games and websites. Consider a blog; unlike a library, it has no
public API. Other pieces of software cannot access it
programmatically. As such, the concept of backward compatibility
doesn't apply to a blog. As we'll explain, semver version numbers
depend on backward compatibility. Because of this dependence, semver
can't version software like blogs.
Source: What Software Can SemVer Version?
It requires a public API in order to effectively apply it's versioning pattern.
For example:
Bug fixes not affecting the API increment the patch version
Backwards compatible API additions/changes increment the minor
version, and...
Backwards incompatible API changes increment the major version.
What represents your API is subjective, as they even state in the SemVer doc:
This may consist of documentation or be enforced by the code itself.
Having read the spec a few times,
Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in
documentation. However it is done, it should be precise and
comprehensive.
I wonder whether all it means is that the consumers of your software must be able to establish the precise "semantic" version they are using.
For example, I could produce a simple script where the semantic version is in the name of the script:
DoStuff_1.0.0.ps1
It's public and precise. Not just in my head :)
Semantic versioning is intended to remove the arbitrariness that can be seen when someone decides to select a versioning scheme for their project. To do that, it needs rules, and a public API is a rule that SemVer chose to use. If you are building a personal project, you don't need to follow SemVer, or follow it strictly. You can, for example, choose to loosely interpret is as
MAJOR: Big new feature or major refactor
MINOR: New feature which does not impact the rest of the code much
PATCH: Small bug fix
But the vagueness of this loose interpretation opens you up to arbitrariness again. That might not matter to you, or the people you foresee who will be using your software.
The larger your project is, the more the details of your versioning scheme matters. As someone who has worked in a third level support for a large IT company (which licenses APIs to customers) for quite some time, I have seen the "is it a bug or is it a feature" debate many times. SemVer intends to make such distinctions easier.
A public API can, of course, be a REST API, or the public interface of a software library. The public/private distinction is important, because one should have the freedom to change the private code without it adversely affecting other people. (If someone accesses your private code through, say, reflection, and you make a change which breaks their code, that is their loss.)
But a public API can even be something like command line switches. Think of POSIX compliant CLI tools. These tools are standalone applications. But they are used in shell scripts, so the input they accept, and the output they produce, can matter. The GNU project may choose to reimplement a POSIX standard tool, and include its own features, but in order for a plethora of shell scripts to continue working across different systems, they need to maintain the behaviour of the existing switches for that application. I have seen people having to build wrappers around applications because the output of the version command changes, and they had scripts relying on the output of the version command to be in a certain form. Should the output of the version command be part of the public API, or is what those people using it did a hack? The answer is that it is up to you and what guarantees you make to the people using your software. You might not be able to imagine all use cases. Declaring the intended use of your software creates a contract with your users, which is what a public API is.
SemVer, thus, makes it easier for your uses to know what they are getting when upgrading. Did only the patch level change? Yes, so better install it quick to get the latest patch fix. Did the major version change? Better run a full, potentially expensive, regression test suite to see if my application will still work after the upgrade.
Related
I am testing these "translate" and "google-translate-api" libraries, they are fantastic, I can translate to all google translate languages directly in react-native, but they can give me problems since it is unlimited and free.
I am building an application with a chat where people of different languages can chat and I am adding the option to translate the chats so that there can be a more fluid communication between people who speak different languages.
When reviewing the code of these libraries I realize that they call this URL: https://translate.googleapis.com/translate_a/single?client=gtx&sl=$%7Bfrom%7D&tl=$%7Bto%7D&dt=t&q=${ encodeURI(text)}`
This gives me the translated phrase as a result, in this way each user (client) can translate the chats directly from the application, but can calling that URL that is apparently free give me any problem?
This is not a legal forum. Nor should you rely on legal forums even if it were the case. Your best course of action is to consult a lawyer that has experience with IP and licenses.
Keep in mind that in general each license has its own caveat. And having available source code does not equal free-to-use as I heard some claim or assume. It is an incorrect assumption and can lead to trouble. Second caveat of license is when using multiple third-parties. Some apparently "free-to-use" licenses (and I say "apparently" as some have some conditions, i.e. not for commercial use) might not be compatible with other apparently "free-to-use" licenses. Again, consult a lawyer on how to handle such scenarios.
This is as far as any "legal advice" can go on this forum. TLDR: talk to a layer.
Using a lot of (official and non official) terraform providers, I'm looking for a tool to perform security analysis on terraform providers before executing terraform plan/apply commands (and so executing providers code). I want to prevent malicious code from providers to be executed blindly.
I'm basically executing terraform providers mirror command to save local copies of required providers and I'm wondering if I can security scan that result.
I tested kics, checkov and tfsec but they are all looking for security issues in my terraform static code but not in providers.
Do you have any good advices regarding this topic ?
This is actually quite a good question. There are many other problems that can be reduced to same generic question - how to make sure that the thing you downloaded from the internet does not do anything malicious to you like e.g.:
How to make sure that a minecraft plugin does not hack you?
How to make sure that a spring boot dependency does not hack you?
How to make sure that a library xxx you attach to your project does not do harm to you?
Should you use docker image yyy in your project?
Truth is: everything you use has the potential to explode right in your face (or more correctly: right into the face of the system owner). That's why the system owner (usually a company) defines a set of rules to follow what is allowed and what is not allowed. No set of rules you are aware of? Below a set of rules we came up with ourselves when thinking about on-boarding a new library for some projects to use:
Do not take random stuff from github. Take only products with longer history, small bug backlog, little to none past issues in the CVE list, actively maintained.
Do static code analysis yourself. Sometimes it is possible to have tools that work on binaries level do that for you. Sometimes you can do it on source level only. In case of Java libraries, check what tools like Dependency Track think about the library and version you are about to use.
Run the code and see how it works: what does it write, what does it read, what URLs does it communicate with (do a TCP dump if necessary).
Document everything you have done somewhere.
This gives you no 100% confidence that things will not go terribly wrong. But this is a systematic approach that will reduce the risk of doing something stupid.
I have a Rails app which is a traditional web application (HTTP requests are processed and HTML pages are rendered). As of now, it does not have an APIs that are exposed to other apps.
I want to use semantic versioning for versioning the application. Currently it is at '0.0.0'.
Quoting from the documentation:
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.
From what I understand, because there are no applications dependent on mine, the major version will never change. Only the minor and patch versions will change, the major version will always remain 0.
I want to know if my understanding is correct. Is there any scenario in which my major version will change?
Since you're not developing and releasing software package, semantic versioning is not directly applicable. It sounds like a single "release" number could be enough for your use case, since what you need is track when a code change will be in test and in prod. Assuming code must go through test before going to prod, you would update the number whenever you update the test environment with code from the development branch. This way, at a given moment development would have release N, test would have N-1, and prod N-2.
API versioning is a different problem, independent of release numbering. In my experience API users only care about breaking changes, so those need to be versioned. Also, since users are slow to update their apps you must be prepared to keep old versions around indefinitely.
One way you could think about this is to think about the user's flow through the application as the basis for versioning. If a breaking change happens (i.e. the user's flow is changed in a way that makes the old route impossible) then it could be considered breaking. If you're adding new functionality that hasn't existed before (i.e. the user has access to a new feature or sees something new on the website that they can interact with) then that could be considered a minor version increase. If you're deploying minor fixes to things like text, then that could be considered a patch-level change.
The problem with this approach, though, is that you need to understand a user's workflow through the application to be able to correctly increment the major version, and as software developers we're still pretty terrible at doing that properly.
Ref: https://christianlydemann.com/versioning-your-angular-app-automatically-with-standard-version
I have this doubt since a while and today I'm not so strong a position, despite having taken one.
Whenever I develop or participate in the development of an application (WEB), typically treat security finger-and-nail, that is, we treat all processes related to security, sessions until encryption of passwords, etc.
I remember hearing someone say that it is always better to use a Framework (Spring, Apache Shiro, etc).
What is your suggestion?
Yes it is always better to use a framework rather then re-inventing the whole wheel again. I personally prefer Apache Shiro and have made customizations to suite my needs by extending classes provided.
REad here http://shiro.apache.org/
Some points to meke up your mids are:
Custom code equals custom vulnerabilities: With web applications you typically generate most of the application code yourself (even when using common frameworks and plugins). That means most vulnerabilities will be unique to your application. It also means that unless you are constantly evaluating your own application, there’s no one to tell you when a vulnerability is discovered in the first place.
You are the vendor: When a vulnerability appears, you won’t have an outside vendor providing a patch (you will, of course, have to install patches for whatever infrastructure components, frameworks, and scripting environments you use). If you provide external services to customers, you may need to meet any service level agreements you provide and must be prepared to be viewed by them just as you view your own software vendors, even if software isn’t your business. You have to patch your own vulnerabilities, deal with your own customer relations, and provide everything you expect from those who provide you with software and services.
Reliance on frameworks/platforms: We rarely build our web applications from the ground up in shiny new C code. We use a mixture of different frameworks, development tools, platforms, and off the shelf components to piece them together. We are challenged to secure and deploy these pieces as well as the custom code we build with and on top of them. In many cases we create security issues through unintended uses of these components or interactions between the multiple layers due to the complexity of the underlying code. When we can use for all other parts why not use for security and just keep and eye if any vurneability is found in that framework and respond by updating as community can update faster and better than by oneself.
I want to use Smalltalk as an embedded DSL engine in C. No plugins required, and whole custom environment will be made by me. So almost ObjectEngine will be remained. Is this possible? I'm currently trying, however any help will be appreciated.
-- edit --
Any of Smalltalk implementation embedding guidance will also be appreciated. (except GNU Smalltalk. Because of it's license...)
This is a difficult thing to do with Pharo/Squeak:
The object engine depends on many primitives and thus many plugins need to be present. A while back most plugins couldn't be compiled statically. I don't know if this is still the case?
Building a whole custom environment is tricky, because it most likely means to strip down an existing image. There are various projects that try to build the infrastructure to bootstrap new images, but I haven't seen working solutions yet.
As Davorin writes Dolphin Smalltalk can be deployed as DLL. Similarly this is possible with Cincom Smalltalk and Smalltalk/X. All these Smalltalk's are commercial though.
To summarize, you are probably better off looking at Lua or Python that have been applied in your context many times already.
There was once a proposal for GSoC but never done:
Packaging Squeak as a DLL
A conventional approach to making libraries written in a particular language available to other languages is to package a library as a dynamic load library or shared object (dll from here on in). Adapting that approach to Squeak would both allow use of Smalltalk code by a wider audience and enable alternative deployment approaches for Squeak applications, easing the creation of Squeak plug-ins for systems like Apache, web browsers and so on. There are broadly two different approaches one can take, which one could call passive or active. In the passive architecture, the Squeak dll is inactive until called from another language, and runs only until a result is answered to the caller. In the active architecture the act of loading the dll causes Squeak to start up on its own thread and accept incoming calls from other threads in a form of rendezvous. The passive approach is easier to build but less useful; one does not have the full range of Squeak facilities such as light-weight processes, delays etc.
The objective of the project would be to implement either the passive or the active approach, depending on the student's interest and ability. The goal is to make Squeak more broadly useful to users and application deployers alike. There are many technical challenges to be met that will involve both Smalltalk and C coding and the use of the Smalltalk-C hybrid language Slang in which the Squeak VM is written.
The benefits to the student include gaining an in-depth understanding of dlls, interfacing to dynamic languages, foreign function interfaces and of the Squeak VM. The student will also be gaining an understanding of architectural issues by considering the many trade-offs between the passive and active approaches.
The benefits to the Squeak community will be in being able to package and deploy Squeak applications much more broadly than before.
Dolphin Smalltalk from Object Arts can be deployed as dll. But you would need to check the license for your particular use case, and it is windows only.