Version 5

[axunonb]

@minichma New discussion about v5

[axunonb]

There is a new label to flag issues or posts with a green "version 5"

[axunonb]

@minichma Created a project https://github.com/orgs/ical-org/projects/3/views/1 and sent an invitation for team "Maintainers" to you. You have access, as soon as you'll accept. I already put first project items there.

[minichma]

@axunonb I don't think I received an invitation.

[axunonb]

Just re-sent now. Currently it's displayed as "pending invitation"

[minichma]

now it worked, thanks

[axunonb]

@minichma
Thanks for your comments to CalDateTime.
The aim of the PR was mainly to fix issues while keep compatibility. Really not sure, whether this is a good way go...
Would your preferred alternative be to leave v4 as is, and (more or less) rewrite v5?

Trying to summarize how I understood the remarks:

Use of NodaTime for Date and Time Representation

Suggestion: Use NodaTime's LocalDateTime, DateOnly, or TimeOnly instead of System.DateTime.

Reasoning: NodaTime provides a more precise and unambiguous representation of date and time values. System.DateTime can be ambiguous due to the Kind property, which can lead to confusion about whether the time is local, UTC, or unspecified.

Action: Consider refactoring CalDateTime to use NodaTime types. This will make the class more robust and less prone to errors related to time zone handling.

Timing: In #638

Immutability of CalDateTime

Suggestion: Make CalDateTime immutable.

Reasoning: Immutable types are generally easier to reason about and less prone to bugs, especially in multi-threaded environments. They ensure that once an instance is created, its state cannot be changed.

Action: Refactor CalDateTime to be immutable. This might involve removing setters from properties and using constructor parameters to set initial values.

Timing: Together with another breaking change.

Necessity of IDateTime Interface

Suggestion: Evaluate the necessity of the IDateTime interface.

Reasoning: If CalDateTime is the only implementation of IDateTime in ical.net, the interface might be unnecessary and could introduce additional complexity without providing significant benefits.

Action: Review the usage of IDateTime. If it is not providing clear benefits, consider removing it and using CalDateTime directly.

Timing: Together with another breaking change. Until then, mark HasTime and HasDate setters as obsolete.

AssociatedObject Property

Suggestion: Re-evaluate the need for the AssociatedObject property in CalDateTime.

Reasoning: The AssociatedObject property might be mixing concerns by combining the representation of a date-time value with operations related to the calendar model. This can lead to confusion and make the class harder to maintain.

Action: Consider separating the concerns of date-time representation and calendar operations. This might involve creating separate classes or methods for operations that act on CalDateTime instances.

Timing: Mark as obsolete in #638

Separation of Model and Operations

Suggestion: Improve the separation between the model (e.g., CalDateTime) and operations performed on it.

Reasoning: Clear separation between data representation and operations can make the code more maintainable and easier to understand. It also helps in keeping the data model immutable and performing calculations just in time.

Action: Review the design of CalDateTime and related classes. Consider creating separate classes or methods for operations that act on CalDateTime instances, ensuring that the data model remains unchanged.

Timing: Undefined.

[minichma]

@axunonb Sorry for being verbose on #638. For whatever reason, probably due to previous discussions, I was thinking that the code was intended for v5, so compatibility wouldn't be an issue. Anyhow, your summary of my comments is quite accurate. All those are just thoughts that came to my mind when reading and working with the code. As CalDateTime is so fundamental, I was struggling with it (and related types like Period) quite a bit. The proposed modifications would have helped in understanding (e.g. immutability, less 'magic'). Looking at the past and current issues, they might also have helped in avoiding some of them (e.g. by avoiding DateTimeKind.Local). That said, it's clear that the changes would come with quite some work and also require consumers of the lib to apply significant adjustments to their own code, which they may or may not be ready for. However, now, after the project was in a sleeping state for so long, would be the right time to do that. I even think that, as people have been living with the v4 issues for so long, and the maintainer's time is sparse, its probably more efficient to invest time into v5 rather than on v4. In some cases it might not even be easily possible to fix v4 issues while maintaining backwards-compatibility. At the same time I must say, that I'm only commenting from the side line, as I probably won't have the time to do significant contributions (sorry for repeating myself). And the comments might be right or wrong, they're just my opinion. It's really on you to decide which way to go.

[axunonb]

@minichma As we both don't have the capacity to come up with a "brand new v5" the way to go could be

• continue improving the current code base as much as possible. If fixing means a breaking change, we publish a new major version, so we can expect more major versions in the near future.
• increase code coverage

Do you see a chance to complete the work about recurrence that you already started?

[minichma]

@axunonb Agree.

If fixing means a breaking change, we publish a new major version, so we can expect more major versions in the near future.

Sure. We should keep in mind though, that new major versions will probably also require ongoing maintenance, so it could be a viable option to introduce a v5 preview/beta/whatever and keep working on that for a while, until we feel the most important changes have been made.

Do you see a chance to complete the work about recurrence that you already started?

Yo mean aside from #598 (that one would b ready and is basically waiting for v5). Sure, I should be able to have a look at a few more recurrence-related issues.

[axunonb]

DATE value type in CalDateTime

@minichma
Currently I'm working on #646.
Reading RFC 5545 Section 3.3.4, where the the DATE value type is defined, it says that the DATE value type represents a calendar date without any time or time zone information.
My interpretation for ical.net is, that initialization with DateOnly should never include a timezone
Besides

public CalDateTime(DateOnly date, TimeOnly? time, string? tzId = null)
{
    Initialize(date, time, tzId);
}

with the time argument NOT nullable we need an overload

public CalDateTime(DateOnly date)
{
    Initialize(date, null, null);
}

which must be used for the date-only case. Am I correct?

[axunonb]

@minichma
Maybe discuss the PR comment here:
My understanding of comparing floating to zoned date/times is as shown in the code above: When comparing a floating date/time to a zoned date/time, the comparison should be based on the values, ignoring the time zone information.
That's the reason for

if (left.IsFloating || right.IsFloating)
{
    return left.Value.Equals(right.Value)
           && left.HasTime == right.HasTime;
}

It's also the reason why this should work for floating date/times - just add the timezone:

    public IDateTime ToTimeZone(string otherTzId)
    {
        if (IsFloating) return new CalDateTime(_dateOnly, _timeOnly, otherTzId);
        // ... non-floating code
    }

Is there sth. I'm missing?

[minichma]

Well, if one has a tzId and one hasn't, then I'd say, they simply aren't equal. One aspect is that equality operators should be transitive. I.e. if new CalDateTime("20241204T000000", "Europe/Vienna").Equals(new CalDateTime("20241204T000000", null) and new CalDateTime("20241204T000000", null).Equals(new CalDateTime("20241204T000000", "America/New_York") then transitivity would require new CalDateTime("20241204T000000", "Europe/Vienna").Equals(new CalDateTime("20241204T000000", "America/New_York") which obviously isn't the case. For that reason it can also easily be a source of bugs.

[minichma]

Here's another example. The following test would fail, if Equals is not transitive (and GetHashCode() is properly implemented, which actually isn't possible if Equals isn't transitive though):

    [Test]
    public void Test()
    {
        var seq1 =
            new CalDateTime[]
            {
                new CalDateTime("20241204T000000", "Europe/Vienna"),
                new CalDateTime("20241204T000000", null),
                new CalDateTime("20241204T000000", "America/New_York"),
            }.Distinct();

        var seq2 =
            new CalDateTime[]
            {
                new CalDateTime("20241204T000000", "Europe/Vienna"),
                new CalDateTime("20241204T000000", "America/New_York"),
                new CalDateTime("20241204T000000", null),
            }.Distinct();

        Assert.That(seq1.Count(), Is.EqualTo(seq2.Count()));
    }

[axunonb]

equality operators should be transitive

Now hopefully I get your point, thanks for being patient.
It's about transitive equality on one side and equality in a certain context like zoned vs. floating date/times, which is not the same thing For the latter latter we need another method to compare, and it cannot be an equality operator.
Correct?

[axunonb]

Committed to PR in cd878f9

[axunonb]

CalDateTime.AsDateTimeOffset

@minichma
As far as I see, in #658 this is the only place left, where DateTimeKind.Local comes into play.
The system's local timezone may or may not be the right context for the user.
Would it be good way to implement a setting for the user's local timezone? If so, where should this setting go to?

/// <inheritdoc />
/// <remarks>
/// If the <see cref="TzId"/> is <see langword="null"/> or does not represent an
/// IANA or other well-known timezone ID, the system's local timezone will be used.
/// </remarks>
public DateTimeOffset AsDateTimeOffset => DateUtil.ToZonedDateTimeLeniently(Value, TzId).ToDateTimeOffset();

[minichma]

As far as I see, in #658 this is the only place left, where DateTimeKind.Local comes into play.

Nice! :-)

Would it be good way to implement a setting for the user's local timezone?

I think the cleanest way would be, not to make the local timezone a special case at all. Rather than having the TZ configured and having special code to deal with it, we could provide methods that can deal with any timezone (which probably exists in most cases) and make it easy for the user to specify their own one, e.g. by introducing something like

public static class LocalTimeZone {

    public static string TzId => DateUtils.LocalDateTimeZone.Id; // or the like

    public CalDateTime Now => new CalDateTime(DateTime.Now, TzId);

   ...
}

Users could then easily pass LocalTimeZone.TzId whereever a tz is required and they want to use the local one. This way we don't introduce additional state that we have to maintain.

[axunonb]

Absolutely! And remove DateTimeOffset, right?

[minichma]

Not sure what it is used for. I never used it. Maybe just remove it and see if someone complains. Or alternatively throw an exception if called on a CalDateTime with floating time.

[axunonb]

CalDateTime.Equals(CalDateTime)

@minichma you remember the discussion about CalDateTime equality.

Exact Equivalence
Currently, equality for CalDateTime means: Same IsFloatingand same Value and same HasTime and same TzId.

Time Zone Agnostic Equality
Both instances represent the same point in time, regardless of their original time zones

In CompareTo(Period?) we cannot use Exact Equivalence StartTime.Equals(other.StartTime.), because the timezone of 2 Periods may be different. and .AsUtc is a must.
My impression is, that the intuitive expectation for Equals is the quality in point in time - not exact equivalence.
Should we use 2 different methods, where one could be EqualsExactly()?

[axunonb]

Just had a short look at the new CalDateTimeSerialilzer in #705. IParameterProvider looks promising, and also no EncodableDataType with CalDateTime 👍

[minichma]

@axunonb I'm continuing the discussion of #705 here, as this is a more general topic, not specific to the PR. In #705 I started preparing CalDateTime to become more flexible by making it more self-contained and more a general purpose class that works independently of Calendar et al. This is nice and helpful in many places, but when thinking forward it might be a step that isn't sufficient or even going in the wrong direction. I.e. all arithmetics, comparisons, etc. depend on timezone handling, which in turn depends on the time zone DB being used. I.e., as the definition of time zones changes over time, arithmetics based on one version of the DB might be different to another one. Consumers of the lib might want to have the flexibility to choose, which DB to use, as they can in NodaTime. (I'm personally using the lib in a project where timzone information is distributed to offline devices, so we actually do have to deal with multiple versions of the DB concurrently.) However, even when decoupling CalDateTime from Calendar as proposed in #705 there still is no context referencing the tz db to be used. As long as we don't support multiple DBs, this is fine, but when thinking about a flexible architecture for the future, we might want to avoid getting in a situation where we don't have the flexibility for improving if desired. So thinking about a design where arithmetics can be based on configurable timezone dbs, there would be several variants, and which one to use is a quite fundamental decision. Here are some variants:

1. Any relevant operation would take a (direct or indirect) reference to the tzdb as a parameter, e.g. CalDateTime.Add(Duration, ITzContext), CalDateTime.GreaterThan(CaldateTime, ITzContext). For the consumer of the methods this would be quite cumbersome as we'd have to pass the context through via all levels of invocaiton.

2. A different approach would be that the relevant operations would not be defined on the classes (CalDateTime, Period) themselves, but on some context class. E.g. ITzContext.Add(CalDateTime, Duration), ITzContext.GetCalDateTimeComparer(), etc. This would be somewhat nicer than the above but would still require a significant amount of refactoring, injecting the ITzContext everywhere. In this case the context could also hold additional config values, like those required for recurrence evaluation.

3. The CalDateTime instances themselves would reference the timezone context. This would make arithmetics very straight forward, as the required information would always be there and signatures would stay as they are today. However, in Calendar et al we don't have this kind of information today and I feel that it is good as it is. I.e. Calendar should not be concerned with timezone arithmetics in any way. So to follow this approach, the way to go would be to fully decouple the ICAL model from the evaluation. So there would be some date/time representation in the model space, which would be what is represented by CalDateTime today, and there would be other classes representing the arithmetics-enabled versions, knowing the timezone context. When doing all the calculations, we would ony be using the latter. All the values that would be returned from evaluation would also be context-aware, so separate versions of Period, maybe Occurrence. This would probably be the cleanest approach, but it would require major rework and would be quite the opposit of what is implemented in Remove interface IDateTime and replace any use with CalDateTime #705. When going this route, we'd rather keep IDateTime, CalDateTime, EncodableDataType and all that stuff as it is and just remove all the arithmetics stuff. We'd rather appreciate CalDateTime being a model object like all the others rather than trying to decouple it.

4. We ignore the potential future need for configuring the timezone context for now and delay the discussion to v6 if at all.

I feel that 3) would be the cleanest approach, which is why I set #705 to 'draft' state. At the same time I see that this would be a major rework that exceeds what is feasible for v5. So maybe continue according to 4). In this case we could continue with #705 and follow a similar approach as we did for CalDateTime also for Period and others.

What do you think?

[axunonb]

Thank you for this very helpful analysis of the possibilities for the further development of ical.net.

As so often, realizing a good architecture is also a question of time and resources. In fact, I would also like the 3rd alternative best. At the same time, at the moment we only have a vague idea of how many users ical.net has today.

While multiple time zone databases can offer significant advantages for certain applications (you gave an example), I'm not sure they are a universal requirement. Users may not need this feature unless their application has specific requirements in terms of global coverage, historical accuracy, custom time zones, high reliability or offline devices. For "average" applications, a single, well-maintained time zone database could be quite sufficient. You have more experience in this area, which is why your conclusion might be different.

Given the limitations and the need to balance immediate progress with future flexibility, it seems reasonable to proceed with Approach 4 for now. This allows us to continue with the current direction in #705 and make incremental improvements. We can revisit the discussion about configurable timezone contexts in a future release (v6), where we can plan an even more comprehensive revision if needed. Perhaps we will have more contributors then.

This also depends on how well the upcoming version 5 is accepted and appreciated by the community.
We could now review our "wish list" and define what should become part of a first public (NuGet) v5.00-pre.x version, and estimate when this could be accomplished.
How does this sound to you?

[minichma]

Sounds completely reasonable and is fully in line with my own view. I just thought it's important to point out that this is quite a fundamental decision for the lib and should be done intentionally.

[minichma]

See the proposals in #739, i.e. move to a model where we use Ical.Net types for representing the model while using NodaTime for calculations. This would allow us to keep some level of ambiguity in CalDateTime (which would be part of the model side) while doing clean calculations in NodaTime.

[ssratkevich]

IStringSerializer.SerializeToString

An one note about IStringSerializer.SerializeToString.
Exploring current implementation of ComponentSerializer.SerializeToString and it's siblings in other serialization classes I noticed, that instead of drilling down callers StringBuilder children always create their owns.
I suggest to have some way to use common StringBuilder all way down in the serialization.
This can reduce memory pressure and allocation of objects that are essentially unnecessary.

[axunonb]

Although not a top priority, we should also care for GC pressure. Please add an issue for this topic, flagged as "Enhancement".

[ssratkevich]

Done:
#702

[minichma]

Now that v5 is available via NuGet, I migrated one of our rea-life projects to v5. The process was quite straight-forward. Here are my findings:

• The way we deal with VALUE=DATE + TZID seems to be not ideal (also see discussion How to associate a timezone to an all-day event #717). In accordance with the RFC we disallow the combination, which can cause problems with data that has been validated and accepted with v4. We have such a situation in our project, so updating to v5 requires us to get in touch with actual customers and ask them to correct their data. This is doable in our case, as only a single, known customer is involved, but this might be a blocker in other projects. Moreover, as we simply ignore the TZID if encountered with a DATE-only value, users can't even detect the problem. I.e. there is no easy way to distinguish floating DATE-only from DATE+TZID. We should at least raise an exception if we encounter an invalid combination, ideally one with a specific type, so the user can detect the situation. (see TBD: Make parsing of CalDateTime strings more restrictive #734)

• CalendarEvent.EffectiveDuration, .EffectiveDtEnd would be handy and should be made public. (see Make CalendarEvent.EffectiveDuration and some conversion functions public. #733)

• Conversion methods between Duration and TimeStamp would be helpful. Those that we have are all internal, for good reason, because they are easy to be misunderstood. However, their use is quite common, so we should offer something with clean naming and docs. (see Make CalendarEvent.EffectiveDuration and some conversion functions public. #733)

• Not being able to configure the TZDB being used, can be quite a problem. In our project it has already been a problem in v4, because we use a tzdb that is different to the one that is shipped with the NodaTime version we've been using, so we ended up doing most of the arithmetics outside of Ical.Net, which is tedious and error prone. Now with v5 (or late versions of v4) we also have a new version of NodaTime, which ships with a different TZDB than earlier v4 versions, which could easily cause issues on our customer's side. Given the discussion we had on that topic, I still assume, that updating the API to make the TZDB fully configurable, is probably out of scope. Maybe we could at least come up with some global configuration of the tzdb, i.e. a global static property holding the TZDB. Would make things much easier already, at least in our case. Prepared a PR for that topic, see Make the time zone resolver plugable #732.

• Dealing with the RecurrenceDates property feels somewhat unnatural. While RecurrenceRules is settable, RecurrenceDates is not. RecurrenceRules can be null, RD can't. I know, we had this discussion before and I'm still quite uncertain, what the right approach is, so probably not something to reopen for now.

@axunonb fyi

[axunonb]

Dealing with the RecurrenceDates

RecurrenceDates and ExceptionDates can only be empty, right. Changing will most likely cause some memory overhead. As you mentioned: Leave this for now.

[axunonb]

@minichma To give you the power to publish packages on NuGet: What is your NuGet account?
If you prefer, submit using this contact form

[minichma]

@axunonb thank you, same as here, just registered. Don't think, I should dive into that process too much though.

[axunonb]

Excellent! Having only 1 person with the power to act is not a lot, so thanks. Won't bother you with this stuff if not necessary :)

[pinkfloydx33]

Is there an estimate for a GA release of v5?

[axunonb]

@minichma
Appreciate your detailed analysis and discussion re #809 on the future of CalDateTime and its arithmetic and comparison methods.

It made me recall that when we started working on v5 we had in mind, that this would be a transitional version anyway, and more releases with breaking changes would follow.

So let's outline a roadmap for the next steps, focusing on minimizing disruption and workload for v5, while preparing for v6, which may again include breaking changes.

1. CalDateTime and Timezone Handling

• Retain explicit support for floating and date-only values in our own types.
• Do not switch to NodaTime’s ZonedDateTime as the public API type.
  • It cannot represent iCalendar’s “date-only” or “floating” semantics, which are essential for standards compliance.
  • Wrapping or extending NodaTime types for these cases would add complexity and even confusion.
• When unifying with NodaTime, use a thin wrapper or adapter pattern, but only if it does not compromise iCalendar semantics.
• Continue using NodaTime internally for calculations, conversions, and validation, but keep our own types as the public API.
• As you said, CalDateTime has the purpose to represent iCalendar. Not being a general-purpose date/time it has deficiencies for arithmetic and comparison. This is can be the role of the new internal CalDateTimeZoned type, and I think it makes handling zoned date/time more simple and less ambiguous.

2. v5 – Minimize Further Disruption

• Keep CalDateTime as the main type for now, but
  • mark comparison operators as [Obsolete] with error.
  • move arithmetic and comparison methods to a new type CalDateTimeExtensions that extends CalDateTime for timezone support.
• Extend Period to (also) use CalDateTimeZoned besides CalDateTime. Add new interal properties Start and End that return CalDateTimeZoned.
• Update EventEvaluator to use CalDateTimeZoned with Period (no change to the public API.
• Above items go into PR Add evaluation classes for CalDateTime #809.
• Merge PR Determine Occurrence.Period by Duration only #808 to return Occurrences as a Period with CalDateTimeZoned for StartTime and a Duration.
• Timeframe: GA release of v5 during the next 2 weeks.

3. Communication

• Communicate the roadmap to users: v5 is transitional, v6 will be a breaking change.
• Invite feedback from users about the migration path and pain points.

This has low impact on existing user code and gives users time to adapt, keeps the API clear, and preserves iCalendar semantics.

How does this roadmap sound to you? Are there any additional points or concerns we should address?

[minichma]

@axunonb sorry for the delayed response, I'm travelling until Friday. Just some short thoughts.

Keep CalDateTime as the main type for now, but

• mark comparison operators as [Obsolete] with error.
• move arithmetic and comparison methods to a new type CalDateTimeExtensions that extends CalDateTime for timezone support.

This is certainly doable. On the other hand, as v5 is just being introduced, its somewhat weird to have many methods marked obsolete already, more so that the final API design of v6 isn't defined yet, so the new APIs might be obsolete by then too. So I think that moving arithmetics to extension methods would be nice, but my recommendation would be to let them replace today's methods. I.e. without additional TZ handling and removing today's methods. I would rather not introduce CalDateTimeZoned in v5, because its a really fundamental change and getting it right might take more time than anyone can invest right now.

Extend Period to (also) use CalDateTimeZoned besides CalDateTime. Add new interal properties Start and End that return CalDateTimeZoned.
Period is a type to represent what can be modeled in ICAL and works nicely for that. It doesn't work nicely for representing recurrences though. So rather than trying to fit the type into something it isn't meant for, I'd rather recommend introducing a new type just for representing recurrences. My recommendation would be a type that consists of a CaleDateTime and a TimeSpan for now. Anyone can then calculate an end time out of it. This would be clean, unambiguous and easy to implement short term. Alternatively keep using Period but only populate Duration and keep End Time empty.

V5 already has a huge benefit over v4, due to all the bugs fixed and other improvements. It's certainly worth publishing it in the near future. V6 may then receive another rework to get the different layers right. (I might not be available as much as I've been for V5 though.)

Hope that makes some sense.

[axunonb]

My understanding was not to expose CalDateTimeZoned to the public API, but to use it internally. That's why I was working on it.

moving arithmetics to extension methods

This could be done, but keeping the arithmetics untouched would not bring any benefit, while it would still be a breaking change for API users.

mark comparison operators as [Obsolete] with error

Comparison operators make use of zoned arithmetic, which is a mixing of concerns. That's why finally they will be removed anyway. With marking them as obsolete we could show a migration path to users. But as there is no alternative yet, we can as well keep them for now.

Extending Period with internal methods

Agree this is mixing concerns, too. We could eventually create a new type for zoned arithmetic, e.g. ZonedPeriod or go any other way.

Alternatively keep using Period but only populate Duration and keep End Time empty.

Yes, this is straightforward (although breaking) and there is PR #808 that does it.

To summarize the discussion:

• Merge PR Determine Occurrence.Period by Duration only #808 to keep Period with only Duration populated.
• Leave CalDateTime as is.
• Release GA for v5.0.0
• Other breaking changes can be done in v6.0.,0, while further bug fixes go to v5.x

Agree?

[minichma]

I see, all makes sense, sorry for missing some of the details. I think #808 is the most straight-foward and the right approach for now.

[axunonb]

Just another thought about model and evaluation layers (not for v5):

Today CalDateTime is already a complex class that mixes multiple concerns, although it's part of DataTypes.

• Contains logic for construction, parsing, formatting, and comparison.
• Exposes properties like IsFloating, IsUtc, and methods for value-based and time zone-aware operations.
• Has multiple constructors for different scenarios, including parsing from strings and handling time zones.
• Implements IComparable, IFormattable, and equality logic.

Almost all concerns are related to the evaluation layer, which is responsible for how the date-time is interpreted and used in different contexts (e.g., formatting, comparisons, time zone handling). It is by no means a simple model.

What we are missing is a model that just serves representing the iCalendar Date and Time Component Properties, similar to this:

public readonly struct CalDateTimeModel
{
    public DateOnly Date { get; }
    public TimeOnly? Time { get; }
    public string? TzId { get; }
    public bool HasTime => Time.HasValue;
}

This would be used for low-level operations like serialization, deserialization and basic value representation without any additional logic. To create and implement this tiny model, would be a lot easier than making CalDateTime become a "real model".

Going this way CalDateTime could be replaced by something like the proposed CalDateTimeZoned including zoned arithmetic and comparison operators.

[minichma]

fully agree

[minichma]

@axunonb Congrats to releasing 5.0.0. This was a major piece of work and a huge improvement. Its great for the community that you took the responsibility and brought the project back to life. Thanks for that also from me in the role of a user of the lib.

Sorry for not being available too much in the last few weeks. I'll continue to be available for some discussions and reviews or recurrence-related fixes if needed. Please don't expect me to be available on a daily basis like in the previous months though, at least for now. I'll also be available for stabilizing v5 as far as possible of course.

[axunonb]

@minichma Congrats to you as well. The new release would not have been possible with your valuable contributions. Thanks a lot! In the past 9 month we dedicated a lot of time into the project, and it's clear we can't go on like that. I'm happy to hear you're still on board. Let's see how the community will receive the new major release.

@NRG-Drink Welcome to the team! How would you proceed with CalDateTime and zone-related methods as mentioned in #606 (comment)? Also, please feel free to pick up any of the open issues if your time allows (just assign to yourself to avoid double work).

[NRG-Drink]

Thank's for the welcome.
It's a little overwelming diving so deep in the conversations. Maybe it's best to start with some smaller issues that I can resolve quickly.
Do you guys have any meetings or do you discuss it all on discussions and issues?

[axunonb]

Oh yes, it took a certain learning curve over the last 9 months for me, too. The whole iCalendar topic is rather complex, but also very useful and interesting.

Up to now, @minichma and I have been using issues, PRs, and discussions to stay on the same page for the project. This approach has its pros and cons, and I'm generally open to exploring other communication channels.

Regarding further steps for the project:

1. Parts of the current bugs stem from CalDateTime lacking the NodaTime.ZonedDateTime that it represents. This makes it challenging to deal with ambiguous or non-existing instants. There are discussions Version 5 #606 (reply in thread) and triage Add evaluation classes for CalDateTime #809, but no decision has been made yet on how to proceed.
2. Regarding optimizations, Optimize IStringSerializer.SerializeToString for less GC pressure #702 and this PR Use dotnet 7 regex source generator #568 are promising. Both could potentially be included in a future v5.
3. Despite the 100+ PRs merged since v4.3.1, progress on code coverage has been moderate. We should keep this in mind whenever possible.
4. Wiki - The number of issues or questions could be reduced with a better Wiki, or at least they could be handled with less effort.
5. A few more things: Project Board https://github.com/orgs/ical-org/projects/3
6. Anticipating what we can expect from more people migrating to the v5 release.

Hope this gives you an idea of where we are with ical.net and what we should/could work on. Maybe look closer at (2) to get started?

@minichma Anything else worth mentioning or prioritizing?

[minichma]

@minichma Anything else worth mentioning or prioritizing?

Not really. Regarding the prios of v5, most efforts were focused on resolving bugs and simplifying things. Several APIs have been simplified or removed in order to reduce ambiguity and confusion. The expectation was that many of them wouldn't be used a lot anyways but now that v5 is out, this needs to be proven. Could easily be that people will be asking for missing APIs and we'll have to decide case by case, how we want to deal with those (e.g. #822).

[NRG-Drink]

Thanks for the verbose list.
I see myself best at the test-coverage. Maybe it's a good way to explore the library as well.

[axunonb]

best at the test-coverage

Really appreciated. Any code changes will become more predictable. This is essential. A first target could be 80,1% 😉
BTW: Unit test are not yet fully migrated to NRT enabled. This can be done first, but also file by file (like we did in the library). It's up to your decision.

[axunonb]

Native .Net Framework support in v5?

@ical-org/maintainers
Up to version 4.11 (5m+ downloads) ical.net included assemblies targeting .Net Framework.
Looking at the current 2,500 downloads for v5.0.0, do you think, this missing target fx might be a reason?

[minichma]

Do I understand correctly, that you consider the 2.5k as too low and asking, whether it would be more if we shipped a version for .Net Framework? Wouldn't think so. Actually it was already dropped with 4.2, which has > 9M downloads and with netstandard2.0 it can still be used with the old framework. And the 5M for 4.11 aggregated over time, so my understanding is that the number not only grows with the number of customers, but also with the time they are using it, mainly due to automated builds downloading on a regular basis. Comparing with 4.3.0, which has 8k downloads but was out only ~1d, the 2.5k for 5.0.0 seem feasible. In the end 4.3 was just a drop-in replacement, no code changes were required, while v5 is a major change, so some adoption delay is fully expected.

So I wouldn't have any concern with current download numbers, nor with a missing target for .Net Framework.

[axunonb]

Thanks. Yes, that was the question. The code changes require additional testing which may delay migration. Let's observe further.
Btw. we get excellent support from AI models: Prompt any of them for sth. like "What is the best iCalendar library for the .NET community" 😉 (to be frank, there are not too many...)

[axunonb]

@ical-org/maintainers Time for a bug fix release 5.0.1? Anything that should get merged before?

[minichma]

#836 would be a candidate, but it might require some additional discussions. Please see my comments there. As it introduces new functionality, we might consider naming the version even 5.1.0 in correspondence with semantic versioning.

[axunonb]

Release v5.1.0 is published

[minichma]

Very nice, thank you! Integrated into our solution and everything looks good so far!