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.

Would it make sense to have a separate timeline module?

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 ?)

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).

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

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.

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?

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

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.

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.