Future organisation of this project

[N-Coder]

For the Timezone handling in #249 we need to somehow ship the Olson timezone database in form of ics files. As this information changes with a schedule different from the releases of ics.py (and both have different licences), it would probably make sense to decouple the ics.py code and the timezone ics data files in two separate repos and packages. I created a new repo and pypi project using my personal account for this, currently called ics_vtimezones. While this works for development and testing, it would probably make sense to have both projects living next to each other once we release v0.8. Speaking of that new version, I guess I currently don't have the permission to push that to PyPi.

So, in terms of truck factor and future development, it might make sense to move the ics.py project together with the ics_vtimezones project into a GitHub organization, resting on multiple people. Similarly for PyPi, I guess it would make sense to not have the projects with only a "single owner", but also with multiple maintainers.
@C4ptainCrunch, what do you think about this? Maybe we should also ask other long-term contributors like @aureooms and @tomschr.

[tomschr]

Hi @N-Coder
moving this project into an organization has some benefits I'd say. For example, you can define teams like reviewers, doc people, etc. That means you can assign PR to a reviewer team and not to an individual. Not sure if that is a huge benefit, as it depends probably on the overall size of the project and its contributors.

Also you can define projects inside the organization itself and repos. That's similar to a Kanban or Trello board and could help maintaining the project.

Another benefit of an organization: each project is an individual repo and so it can define its own workflow, CI, etc.

So all in all, I think it could be worth the price for having the work of maintainers distributed on different shoulders.

[make-github-pseudonymous-again]

Would it make sense to have a separate timeline module?

[C4ptainCrunch]

Hello 👋

About the pypi rights, @N-Coder it definitely makes sense for you to have the rights to publish! I just gave you the "maintainer" access. @aureooms, @tomschr if you feel like it would make sense for you to have access to pypi, please let me know.

About the an umbrella GitHub organization it also makes sense but we have to be cautious as moving the repository to an organization will change the URL. Maybe we could have a look at how other projects have done before ? Maybe take the Pallets projects as an example ? Here is a non-exhaustive list of things that would break/would need to be updated:

• Read the Docs integration
• PyPi project homepage
• README.md URLS

Nevertheless, i already parked the github.com/ics-py and github.com/icspy namespaces just to be sure. 🤞
(Side quest: dots are not allowed, should be use the dash or not ?)

[N-Coder]

Would it make sense to have a separate timeline module?

You mean the Timeline class and code from ics/timeline.py? That depends a lot on the Timespan class which is somewhat generic, but still has a lot of custom code specialized for ics events and todos. So while the Timeline has some somewhat generic code that isn't directly related with ics, it would probably be hard to decouple it and I don't see a strong reason for doing that.

The project I mentioned above is only for Timezones and only contains generic ics data files, which could e.g. also be parsed by dateutil's tzical. So an ics_vtimezones package might also be useful without the ics.py package. Our code for parsing timezones would also remain within the ics.py project, as it also heavily relies on the parser infrastructure. The ics.py package would have a dependency on the ics_vtimezones project for providing the data files (but nothing more). This also allows decoupled version for the data files (similar to what the Olson database uses, e.g. 2020d) and for our code (like v0.8).

[N-Coder]

About the an umbrella GitHub organization it also makes sense but we have to be cautious as moving the repository to an organization will change the URL.

If you transfer the repository, GitHub will forward anyone using the old links to the new home of the project (see the very last point here), so nothing should break immediately, but we still should update all links to directly point to the right place as you said.

Read the Docs integration

Should we also think about the organization on RTD?

Nevertheless, i already parked the github.com/ics-py and github.com/icspy namespaces just to be sure.
(Side quest: dots are not allowed, should be use the dash or not ?)

Naming is, as always, the hardest part. I sometimes get confused whether I should type pip install / import with ics, icspy, ics-py, or ics_py, while usually using ics.py in text. To not further add to that confusion, I'm strongly in favour of a somewhat consistent solution (hint: pip install ics and import ics are the currently correct versions, on RTD we have icspy.readthedocs.io and call the project 'ics.py' in the texts there).

As github.com/ics is already taken (and we actually are a python-specific project) while the 'py' is also usually not part of the name in python code, I would prefer github.com/ics-py to icspy to show that the 'py' is something separate. If we instead were to use 'icspy' more often, we probably should also migrate to pip install icspy and import icspy (underscores look weird in PyPi project names and dashes don't work in python code), which I don't really like. Using 'ics.py' as project name in text is probably still okay, so the only thing we need to think about is the URL of the repo itself, which currently is github.com/C4ptainCrunch/ics.py (weird that GitHub allows dots in repo names, but converts them to dashes in organization names). Maybe we should also use a dash there for consistency, resulting in the following naming scheme

• the project is called 'ics.py'
• its websites are github.com/ics-py/ics-py, ics-py.readthedocs.io
  and pypi.org/project/ics (for the last one the python context is clear)
• it can be installed using pip install ics
• it can be imported using import ics

[tomschr]

I agree with Nico, naming is the hardest part.

Just to add one thing to this discussion: If we agree on a naming and it's done, maybe it is a good opportunity to release a new (major?) release? Just reflect this on PyPI, RTD, READMEs, etc.

[make-github-pseudonymous-again]

You mean the Timeline class and code from ics/timeline.py? That depends a lot on the Timespan class which is somewhat generic, but still has a lot of custom code specialized for ics events and todos. So while the Timeline has some somewhat generic code that isn't directly related with ics, it would probably be hard to decouple it and I don't see a strong reason for doing that.

Understood.

The project I mentioned above is only for Timezones and only contains generic ics data files, which could e.g. also be parsed by dateutil's tzical. So an ics_vtimezones package might also be useful without the ics.py package. Our code for parsing timezones would also remain within the ics.py project, as it also heavily relies on the parser infrastructure. The ics.py package would have a dependency on the ics_vtimezones project for providing the data files (but nothing more). This also allows decoupled version for the data files (similar to what the Olson database uses, e.g. 2020d) and for our code (like v0.8).

Can you explain precisely what kind of layer would ics_vtimezones add between ics and these data files. What are the sources of these files? Everything comes from Olson timezone database? Why not call it olson instead of ics_vtimezones?

[make-github-pseudonymous-again]

I can see a few python packages that seem to bundle these files (https://pypi.org/search/?q=olson). None of these are usable?

[N-Coder]

Sorry for the late reply, this week has been busy and the answers to Auréliens questions will be a bit longer, so I'll post them later to the corresponding PR #249, but you might want to start with reading my initial thoughts here.

Just to add one thing to this discussion: If we agree on a naming and it's done, maybe it is a good opportunity to release a new (major?) release? Just reflect this on PyPI, RTD, READMEs, etc.

Doing an (or at least one) intermediate release sounds good, we also have some smaller changes that could make it into a v0.7.1 release for anyone who doesn't want to do the necessarily manual upgrade to v0.8. We also have quite a few breaking changes, of which we should make our users aware before they do an auto-update without having the ics.py version pinned and then run into trouble. Examples are the removal of Arrow and the changed serialization / to string behaviour (see #240):

The most important change might be that all custom __str__ and __repr__ methods were removed. Previously, __str__ returned the ics string and __repr__ returned a very short informal description, which made dumping the actual python values hard when debugging. [...]

To summarize, the new methods are more aligned with python coding standards and work as follows:

• __repr__ returns a full, valid python representation, is fast and can't throw exceptions
• __str__ returns a short human-readable description, is fast and can't throw exceptions
• serialize returns the full ics representation, is still pretty fast and usually shouldn't throw exceptions (except for when you pass in data that can't be serialized, this potentially includes old Arrow instances)

So someone who blindly upgrades from v0.7 to v0.8 might still serialize their iCalendars using __str__, not realizing that the new implementation no longer returns the full ics data but just a short description of the object, leading to potential data loss.
I thought about adding deprecation warnings to an intermediate release, but these can get annoying quickly as the method still has a very good use and also potentially don't reach all users, e.g. those who don't see the ics.py output as it runs in the background or those who skip the intermediate release by only upgrading after the final v0.8 is released. A better way might be changing the constructor of the iCalendar class, so that old code that hasn't been upgraded surely breaks, and providing an easily accessible upgrade path. We could drop the imports parameter to Calendar.__init__ and also rename Calendar.parse_multiple, so that old code can't accidentally create an instance with the new behaviour. An example for a new API might be:

# old
cal = ics.Calendar("BEGIN:VCALENDAR...")
cals = ics.Calendar.parse_multiple(open("merged-calendars.ics"))

# new
cal = ics.load("BEGIN:VCALENDAR...")
cals = ics.load_multiple(open("merged-calendars.ics"))

We could change the old methods so that they throw an exception with a helpful message pointing people at our migration guide.

[tomschr]

Apart from all these changes, which are probably all necessary and useful, I would like to focus on an additional topic (usually completely underestimated): the migration from old to new.

You can change names, move functions from one file to another, or add additional features. That is all fine and the daily work of any developer. However, I strongly believe all these changes needs to be documented. Especially if you introduce incompatible changes. 😉

I have the following use case in mind: if a developer using your project from an older version and wants to move to the new version: what does this developer need to know? What are the little (or big) traps? What does he or she need to do?

It doesn't need much. A short chapter describing what needs to be done (and maybe why) is all what is needed. If the changes are self-explanatory and simple, this task can be done by a well maintained changelog. However, sometimes, this is too dense so a separate chapter/section etc. is probably the better solution. There you can give more background, add examples etc.

---

Tl;dr: add a chapter or section describing all incompatible changes and how to migrate from the old to the new version.

[C4ptainCrunch]

While browsing GitHub i stumbled upon the @jazzband organisation.
It also seems like a great way to limit the truck factor. What would you think of moving the repo over there instead of creating an ics.py orgnaization ?

[C4ptainCrunch]

What shall we do ? I suggest a vote open for 5 days (closing on the 21st, 23:59 GMT) with the following options:

1. Keep the status quo and host the repo under github.com/C4ptainCrunch/ics.py
2. Move to github.com/ics-py/
3. Move to github.com/icspy/
4. Ask a transfer to github.com/jazzband

I'm voting option 3.

@N-Coder @tomschr @aureooms i'm tagging your to be sure you get a notification. Others are welcome to vote if they want to :)

[N-Coder]

Hey, thanks for bringing this up again!
The idea behind jazzband sounds pretty cool, but it seems like there is actually only one person actually doing the roadie part and joining the org as a member is an automated process (which 800+ people already used), so that kind of means public write access to all the repos.
I guess we're pretty safe on the truck factor side with the 4 of us having write access to our org, so joining jazzband might be kind of a backup for the last person if the three others ever go missing for a long time.
Also, I think the reasoning from my previous post is still valid, so I vote for option 2 github.com/ics-py/ics-py

[tomschr]

Thanks for bringing this up again!

What shall we do ?

I'm not sure if I can help here as much as I'm not a very active member. 😉 However, I can provide some ideas.

I think, renaming the GitHub repository or moving it to another domain is not so the problem. It's always possible. People who use still the old URL will be redirected automatically to the new one by GitHub.

So from my point of view, it's only partly a technical issue, but more of a "social". For example, I'm thinking about these questions:

• What would be the most natural or logical name when people try to find a Python project like this?
• Have you considered an option 5 for a domain github.com/ics.py (a dot instead of a dash)? 😄 Wouldn't that resemble the old name better? Would it easier to remember?
• What are the pros and cons for living under a foreign domain like Jazzband?
• Do we share some common goals with, e.g., Jazzband? In terms of community, code of conduct, etc.

Maybe I missed these discussions and they are already solved some time ago. In that case, sorry for bringing up old stuff.

Not sure if I'm not qualified enough to answer these or even vote for one or the other. 🙂 But as you asked me and if I really have to decide, I would go for option 2 or 3 for the following reasons:

• Easier to create different teams if is needed (review, doc, security, etc.)
• Shorter name (ics-py/icspy/ics.py) in comparison to C4ptainCrunch 😉
• Independent from any user account. A new domain can help in terms of infrastructure (project view, GitHub Actions, subprojects, etc.)
• Probably easier permission handling as it's independent from any user account (see team permissions)
• A space like ics-py.github.io/PROJECT if we want to present our project.

I know, none of the above points are real "killer features". However, the combination is compelling to move it to an own domain.

Moving it to a different domain (like Jazzband) would be too "disruptive" and too "radical" IMHO. If there are really some compelling and convincing arguments we could do that. This could be an option for the future. However, for me, it's not clear to me what the pros and cons are.

Hope that helps. 🙂

[make-github-pseudonymous-again]

I vote for 2.

[C4ptainCrunch]

Option 2 it is ! We are moving to github.com/ics-py/ics-py :) (sorry for the lag)