Contributing a small change - future release plans? (1.x and 2.x)

[Shaun Malone]

Hi,

My colleagues would like to contribute a small change to make the stop_sequence accessible via the IndexAPI under /trips/{tripId}/stoptimes.

If we managed to get the change approved and merged into the dev-1.x  and dev-2.x branches, is there anywhere we can see how releases are planned and understand which release versions it may end up in?

I think we would need to run our own custom build until a formal release was available but obviously we would be keen to stick with official builds, and if 2.x releases are more likely than 1.x, we could start preparing now by upgrading to 2.0 (we're currently running 1.4)...

Many thanks,

Shaun

[Thomas Craig]

Hi Shaun, thanks for your work on OTP!

There's no defined location where release dates are written down, and releases are made when the PLC feels the code is ready for a new version. The best way to keep up with those discussions is to attend PLC meetings or check in on the PLC meeting notes.

At this time, a release for 2.x is planned in the near term, but no new releases of 1.x are planned at this time, so if the goal is to get your change into a release, a PR to dev-2.x would make more sense. Based on what you've said, two items come to mind for me:

- (you're likely already aware but just to highlight) there are some features present in 1.4 that aren't included in 2.0 so that might affect your plans (more information in the migration guide)

- it sounds like your change is to the REST API, (forgive me if I'm wrong on this, I'm not a developer just a prod person). Some components of the REST API are deprecated in 2.x and the general plan is to preference the GraphQL API from here on out. I'd advise making an issue on the repository first before going through the process of putting together a PR just in case one of the core project developers wants to comment on the issue. (Or Thomas G, Andrew, Gard or another dev might comment on this thread.)

All the best,

Thomas Craig

[Shaun Malone]

Hi Thomas,

Thanks for your warm welcome and advice, hope we can make some small contribution to this great project.

Thanks for the headsup about the 2.0 changes: we were aware there are some breaking changes and expect a reasonable amount of work here, though we didn't spot the migration guide yet, so that's super helpful.

That's a good point about the GraphQL API - we use that too and will be keeping an eye on the OTP 2 plans in that area (Legacy, Transmodel and New APIs) - I will add an issue to the repo, and hopefully that will spur some discussion about the best place to make this change!

Cheers,

Shaun

[Shaun Malone]

Hi Thomas and OTP devs!

We're still really keen to get our change integrated, but are not sure how to move forwards with our PR https://github.com/opentripplanner/OpenTripPlanner/pull/3527

I'm guessing that PRs for 1.x are really low priority compared to anything for 2.x, if so, should we submit an equivalent PR for 2.x?

Without getting this change in to at least the 2.x branch, we are uncertain whether we will have a future upgrade path and may need to re-architect this part of our system as a result.

Many thanks,

Shaun

[Andrew Byrd]

Hi Shaun,

Thanks for the additional details you provided on the issue and PR. I have summarized the current situation in comments on the issue and the PR:

https://github.com/opentripplanner/OpenTripPlanner/issues/3528#issuecomment-892403369

https://github.com/opentripplanner/OpenTripPlanner/pull/3527#issuecomment-892411532

In short, we’re hoping to get this merged at our next meeting.

I see that this relatively simple change stalled for a while, and it was unclear to the participants why this happened. Having just read through the comment history and thinking this through, here are a few suggestions and observations that might help other contributors in the future:

- In issues and PRs, clearly describe why any change or feature is needed, not just from the perspective of the contributor but from that of other users of OTP. These days we try to be very deliberate about what features are added, considering the ongoing long-term effort of maintenance and coordination. It is always an option to have unusual or special-purpose features in your own branch of OTP; features added to the main OTP repo should be of more general interest. On the other hand, no real justification is needed for “sandbox” contributions, which will be merged with cursory review as long as they are isolated as described in the documentation. http://docs.opentripplanner.org/en/latest/SandboxExtension/

- Always clearly describe or distinguish between OTP 1.x and 2.x in issues and pull requests. Describe whether your changes or problems apply to one or both of these branches. It’s not essential to consider OTP 1.x if you are only contributing to the current 2.x codebase. But we will need to verify whether any 1.x contributions can be ported over to 2.x and whether they are relevant in 2.x. Ideally the contributor will do this research and explain the situation in the issue/PR.

- Changes to OTP 1.x will not be prioritized. No further 1.x releases are planned, so (with possible rare exceptions) the 1.x-dev branch is expected to receive only critical bugfixes and not new features. The core OTP development team must generally respect the priority of their employers and clients, which is OTP 2.x.

- Always provide a prominent link from PR to the issue it solves, ideally in the first comment on that PR (the PR description or even title). Please provide concise, clear descriptions of issues or solutions even if it seems a little repetitive (restating the same thing on one or more issues or PRs that are related). Developers often have to juggle hundreds of tickets from multiple projects (OTP may not even be their primary project) and these bits of extra information can make this process much smoother.

- Development resources (i.e. software developer time) are limited. The people reviewing and managing issues are employees or contractors of agencies and companies with their own commercial or public service objectives. We have follow these priorities and realistically not everything is going to get done. These organizations want the OTP community to thrive, but can only spend so much time and money on that broader goal. The overhead of project management, architecture, and governance are significant. Organizations expecting to contribute nontrivial changes should expect to devote significant time to discussions, meetings, and issue management, not just writing code.

- A culture has emerged of seeking consensus on any new changes or features and subjecting them to critique by other developers. This has been happening primarily in our twice-weekly developer meetings (video/audio calls). Experience shows that the consensus/critique/finalization process goes much faster and much more smoothly in this context, compared to email and text comments. Almost all PRs merged recently were debated, revised, and merged during these meetings. If possible, join one of the developer meetings. This will get eyes on your issue or PR immediately, and resolve any questions immediately to unblock progress. The meeting times might not be good depending on where you're located - in that case, if progress seems slow, please try to set up an earlier or later call with whoever is reviewing your issue. 

- It’s August, and in the high latitudes of the northern hemisphere (where a lot of OTP developers are currently located) this is vacation season. Around this time of year (as well as the second half of December), it is possible that development activity or communications will slow significantly or even halt.

I will try to pull these and some other recent suggestions into a CONTRIBUTING file in the OTP repository, which Github will make visible to all new contributors.

Thanks,

Andrew

-- 
You received this message because you are subscribed to the Google Groups "OpenTripPlanner Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to opentripplanner...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/opentripplanner-dev/8dc83541-beb3-4516-ad8a-15f53ff207cen%40googlegroups.com.