11:08 a.m.
Hi Ivan,
For what it matters my opinion I agree with what you said.
Generally we could introduce a template/boilerplate for new projects:
README, LICENSE, CI, CONTRIBUTING ...
It would speed up the creation of new projects with an idpy standard
configuration in terms of policy, structure and functionalities (CI).
Documentation
--------------------
I'm experimenting the Doc-first approach, me and my colleagues are in the
second project developed with these principles.
Practically, we get or define new design principles and features from tech
specs or creative thoughs, then we work on the semantic of the variables
and the peculiarities of the features, directly in the Documentation.
Starting from it, then we develop in code. We're feeling like the amount of
work is reduced, by three side:
1. Coding: the important choice in terms of design and material definition
of problem and solution have already been addressed during the drafting of
the documentation (it happens, magic!)
2. Documentation: comes in addition, like it would have been designed as if
it was drawn directly around the users, starting from the end!
3. Time: there is the perception that everything is more natural, it
definitely reduces the psychological costs of an asynchronous development
between code and documentation.
An example that could drive us in this goal would be the problem we're
facing in pysaml2 regarding the Algs used.
We have some sparse and highly specialized PR (not to say hardcoded!) and
what we are missing is a definition of the semantics of the variables that
should guide us in the default evaluation and in the definition of
blacklisted ones, well, this would start from documentation. Finally,
documentation would be the first place where planning and analysis would
take place, with a form of final result.
Versioning
--------------
Semver is great and easy, the best choice.
I often wonder why pysaml2 satosa have a strange versioning, let me
explain, it formally is perfect but ... These projects follow a CI approach
that pursues the creation of many small releases, but it is too often the
major release that is increased.
Currently pysaml2 is 6.3.0 and SATOSA 7.0.1 and I often wonder what
revolutionary feature may have advanced the major release, considering that
a fairly simple configuration works as it is and without changes, with the
latest releases released in the last 3 years.
But these are just mental saws, we should talk about something else,
forgive me!
Changelog
---------------
This is a real divide between reality and theory! There would be many
things to say but better say as little as possible (despite the length of
this email).
Preserving the sanity of us developers, we would assume that each commit
has a minimal description of the goals achieved. Extracting these and
formatting them decently we would pull up the changelog without too much
performance anxiety :)
The quality of our commit descriptions is the key to success, if the
commits are not described well include this goal in our PR reviews. This
should be enough to get a semi-automatic changelog approach, hopefully!
Changelog is the first place a sysadmin would try to know if the new
version breaks anything ... It only matters if it was written well enough!
some things may sound brutal but you know me, don't get me wrong, thanks
for everything!
G
Il giorno mar 10 nov 2020 alle ore 23:53 Ivan Kanakarakis <
ivan.kanak at gmail.com> ha scritto:
Hello everyone,
at the last idpy meeting, we started a discussion around normalizing
how idpy projects operate. The goal is to agree on a baseline on how
we treat different project aspects and how we can harmonize those in
order to give users uniform expectations. A user that is familiar with
how project-x works, should automatically be familiar with how
project-y works when they decide to use that too. The first step is to
agree on guidelines, and then have each project steadily work its way
to that. In the process, we should effectively be cultivating a
culture on how we manage projects, and not blindly follow policies.
The initial discussion started around documentation, versioning and
changelogs. Many more things can and should be discussed. Those
include topics such as tooling, CI/CD, testing, packaging, release
schedules, issues management, git-workflow, etc. I will expand on some
of those topics and we can further discuss in this or separate threads
or in the following calls about each one.
## Documentation
I think we can all agree that documentation is important and needed. I
make a distinction between documentation whose audience is a user and
documentation whose audience is a developer. The user-documentation
consists mainly of the project API, how it is used, and use-case
scenarios. The developer-documentation consists of architectural
diagrams, design choices, separation of entities, and general guidance
on how modules are separated and code is organized.
Being part of the python community, the natural tool around
documentation is https://readthedocs.org/. Readthedocs works in tandem
with Git(Hub) projects, and can automatically be kept in sync with a
repo.
- Do we agree to use https://readthedocs.org/ to publish documentation?
- Should we request PRs to include documentation? or, should we
fill-in the documentation when creating a new release?
## Managing change
### Versioning
What we actually want to do with versioning is _signal_ the type of
changes that are part of a new release. The most common versioning
scheme is semantic versioning (https://semver.org/) - other things out
there include CalVer (https://calver.org/) Apache versioning
(https://apr.apache.org/versioning.html) and more. However, I think
semver is quite common and probably everyone will agree that it's
fine. Most importantly it achieves the goal of signaling in a simple
way:
--
____________________
Giuseppe De Marco
Centro ICT d'Ateneo
Università della Calabria
87036 Rende (CS) - Italy
Phone: +39 0984 496961
e-mail: giuseppe.demarco at unical.it
Given a version number MAJOR.MINOR.PATCH,
increment the:
- 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.
Additional labels for pre-release and build metadata are available
as extensions to the MAJOR.MINOR.PATCH format.
- Do you think we should use semver?
### Changelog
Same as with documentation, the Changelog comes in two flavours - the
changelog that is intended for developers, and the changelog that is
intended for users (aka release notes). The technical-changelog is the
VCS-log itself and contains purely technical entries on how the code
was modified to achieve a certain effect. We have the technical
changelog for free.
On the other hand, the user-changelog has the form of a set of release
notes. The release notes should be enough to explain what’s going on
to someone deploying the package, or to a user that wants to use new
functionality - it is a summary of the new release value. This type of
changelog cannot be autogenerated, and we must write and curate by
hand. As with versioning, there are some formats out there, but I
think something like keepachangelog (https://keepachangelog.com/) is
easy to use and very close to what most of us would end up with while
trying to specify a consistent format.
When should the user-changelog be updated? Usually this is done either
at release-time.
- Should we maintain a changelog/release-notes?
I will continue this subject with more topics, soon. I'm looking
forward to your thoughts!
Cheers,
--
Ivan Kanakarakis
_______________________________________________
Idpy-discuss mailing list
Idpy-discuss at lists.sunet.se
https://lists.sunet.se/listinfo/idpy-discuss