[Idpy-discuss] Normalizing across all projects

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: - 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