News and Info on Django-Address Development
Opened this issue · 49 comments
Hello, I've recently joined the django-address maintainer team.
Here is a proposed pathway forward. We'll happily take feedback from folks who have submitted PRs in the past, have forked the project or just have lots of experience working with addresses.
- Launder existing open tickets and set up triage release milestones:
- Close those no longer valid, completed or other status.
- Create one ore more 'triage' milestones
- Classify those Issues that are still valid and add them to the expected triage release milestone
DONE! See this comment.
- Review and handle open pull requests
- In coordination with ticket laundry, we'll review all open PRs and merge toward a milestone above or provide other resolution.
- Review status of project branches
- Understand if they include work from existing issues or PRs
- Understand what direction they might be pointing the project
- Remove if stale
- Identify any points of issue with the current structure or feature design of django-address. (See Address Model Notes)
- Review changes in address geocoding responses from major APIs
- Review changes in Google Maps, MapBox and Open Street Maps (see Scope Considerations)
- Review updated forks of this project for ideas
- Review popular address packages from other web frameworks
As a courtesy, I'm going to mention folks who have pending PRs or Milestones in this project. Please feel free to reply with feedback on this path forward, or to say hello.
If you have a PR or Issue that you want urgent attention to, please add a new comment to that PR or Issue and link to it from here if you reply here.
Addresses are an incredibly important part of web applications, and with Django as the best (imho) mature web framework, this project deserves to get attention.
I'm hopeful we can work together to make it a very desirable package for Django developers everywhere.
Open PR submitters: @mattijevi, @waam, @ahkim, @ZuSe, @klowe0100, @karbassi, @arbeiterz, @corysutyak, @blocher, @Benbb96, @msarahan, @awh4kc, @kbhalerao
Recent Open Issues: @yatahaze, @peiliu, @samkamin, @rubenmafe, @coler-j, @spakker, @xhiscortz, @ZuSe.
Hi @banagale
That's a good initiative !
This package seems to be working pretty well out of the box.
But I forked it to have a better appearance (PR #79 and Benbb96@c2caf90)
I also opened a PR to update some things in the README ( #93 ) but I don't think any of this is urgent 😉
@Benbb96 Thank you for the PRs going back two years. I've added both to a new milestone, Ticket and PR Triage 1. This does not mean they will be pulled but at the very least my hope is they will be slotted into a to-be-created release milestone with a deadline.
Are you using django-address on any current projects? Please feel free to discuss a bit about how you use it and why.
@coler-j Thank you for the reply. I've closed #85 which was resolved in #94. If you have any comments on django-address from when you did use it, please feel free to leave them here regardless.
@banagale Cool 👍
I'm using django-address for my current project in my company. We needed a simple way to add an AddressField with an auto completion feature from an API like Google Maps and this package really do its job for that !
Made a first pass at processing open tickets this morning. Also created a first target triage Version 0.2.2 Release for 4/23/2020. Focus there is on Python 2.x and Django 3.0 compatibility.
I've set a follow-up Version 0.2.3 Release to focus on bugs for 5/7/2020.
@banagale Whichever direction you decide to go, I cleaned up my PR, let me know if there is anything else I should do with it
@moritz89 @awh4kc Thank you. Django 3 support is the focus of the immediate release. While I appreciate @awh4kc's commit of offering python2 support I am leaning away from this at this time.
Reasons:
- This package needs a lot of love, so less to support is better.
- The package may get new dependencies if features or scope is added. So booting p2 keeps things a bit more trim.
- Since addresses are such an important part of web applications, I believe new releases of
django-addressshould tow the line that python2 is out of support as of January.
I'm open to convincing otherwise.
For now, I've self-assigned both pull/95 and pull/96 and one of them will be a candidates for Version 0.2.2 Release
@moritz89 @awh4kc After speaking with @nsasch I'm going to reverse myself and say that we should support Python 2 until we have a more stable release. So here's a revised path forward for Python2:
- Final python2 supporting release will be 0.2.3
- I've added a new milestone, 0.3.0 which will work on structural issues and will drop support for python2 and its necessary dependencies under Django 3.
@banagale Either way works for me, I definitely see the rationale behind not including it, especially going forward
I'm going to provide some context since you'll see that 6/23 existing open issues were filed by me, though at least several years ago. I run www.morphmarket.com which has been using this library since 2015. We use it for our sellers to indicate their location for search and also rendering on a Google Map. Back then we had about 100 sellers, and today we have at any given time about 3,000 across the world.
I have an extra layer of predicament here -- we are on the dev branch, so I don't know how many of the bugs we're seeing are affecting others or if we are just suffering alone. I don't even remember what the differences are with the dev branch, but that's where Luke directed us. I will see if I can get him to chime in on that issue again.
This "pathway forward" topic comes at a good time for us. I have hired some help and we are currently doing the Python 3 upgrade, followed by Django 2 and 3. As part of that process we need to either get the dev branch merged (which I imagine is unlikely), get onto the master branch, or find a new solution.
I added django-address to several different "grids" (tags) on https://djangopackages.org/. It's not clear to me where it was listed, if anywhere. That should help our marketing just a bit.
@jplehmann Thank you for sharing that context and the project you're using django-address on. How many snakes do you have and which is your favorite?
As Luke mentions in #45, dev and master have diverged quite a bit. It appears dev was intended to completely abstract an Address from classification of its components.
After implementing django-address's master branch myself, it feels like the current model architecture is likely not abstract enough. I do not know that it should be as abstract as dev.
Instead, I'm looking at the response formats from major address geocoders like Google Maps and Mapbox. I've also got my eye on Nominatim and OpenAddresses address component schemas. Also worth consideration is how libpostal parses addresses into components.
Ultimately, whatever underlying model architecture changes we chose may matter less to users of this library than whether forms and model accessors exist that make sense for the country or countries they're dealing with. For example:
- "I'm in the United States and I want to store each address's County, so I can filter on that. How do I get or set County with
django-address?" - "My site is focused on Quebec, I need to store the province and province abbreviation, how does
django-addresshelp me with this?
One of the biggest issues I've found with Addresses is can be quite complicated for programmers to handle, yet if you're reaching out for a library to help you handle this, it should not require you to be an expert to make good use of it.
But regarding your potential need to migrate from dev: I don't know what the model architecture changes from master will be in 0.3.0 yet. And so it is not clear how easy it will be for you to migrate from dev.
If, once we are finalizing architecture changes, more people speak up about wanting to migrate from dev, then perhaps we can work together to provide migration so it can be fully deprecated.
Regardless, dev has diverged so much from master it probably must be renamed to a new branch, and a new develop that is the basis for the "next" release should come into being.
Okay! We've successfully accomplished step 1, Launder existing open tickets and set up triage release milestones! We closed 22 tickets in 11 days in this stage. Also, every single open issue has been reviewed and is now assigned to an open milestone.
In this process I've been very appreciative of the folks who have commented on issues, sometimes even if they are very old. I really appreciate that people are out there keeping an eye on django-address and hope I can reach out to you for testing and feedback as we work to polish the project up. :)
The most important thing is to get this current with Django 3 and still support Python ASAP. This is what 0.2.2 is focused on.
I've pushed the milestone deadline to 4/29, though my goal is to have that version up on pypi on that day, so it should be ready and tested well in advance of that.
For now, I'm bumping this issue to 0.2.2, so there's a clear thread of communication about what's going on with this project and I'll probably keep it bumped until we get 0.3.0 out the door.
Continuing to talk about dev branch here (in lack of another name), since other issues have been closed out.
If, once we are finalizing architecture changes, more people speak up about wanting to migrate from dev, then perhaps we can work together to provide migration so it can be fully deprecated.
Rob I doubt few others are going to come forward who are using dev. And I seriously doubt we ever needed what support it provided in the first place. I actually don't care about granularity any more detailed than "city" (don't want house address). I can't see that being too complicated to encode and imagine master would do just fine.
So, do you think it's easier for us to migrate to the current master to get in the groove with everyone else, or will it be easier to go straight to the newer version?
@jplehmann You missed my snake questions.
Regarding model architecture, I think Luke was on the right track offering greater levels of abstraction. They are necessary to cover things like county and neighborhood. Although I am in the United States, most folks are not and a lot of non-US addresses need it.
It would be nice to offer convenience methods or properties for common address elements. It would be nice not to have to understand what a locality is, for example, and just be able to get address.state or ‘address.city‘.
In addition, we need to think about the number of joins required to display an address.
To answer your question though, I think Your best bet is to wait for 0.3.0 because it will have to have a different structure than what is currently on ‘master’.
I will create a model architecture focused ticket so we can split off this topic and focus feedback on a series of proposals.
Quick note for folks paying attention, I was not able to work on the PR in anticipation of today's first release milestone. I'm planning to work on this later today.
I made some progress this eve:
- Created develop which will be the branch that is used to build toward
mastergoing forward. (Recalldevhas diverged) - Created Future Project To-Dos to house unprioritized tasks that enhance
django-addressas a project - In preparing to pull a PR, I realized I needed to repro the issue on both versions of django so created #101 so I could do this locally.
This project needs some work, and it has been a while since a release. I suppose some more time won't hurt. I think its better to take it slow and get the start right than blow one of the first few releases.
As a result, I've moved all release milestones out one week. With a goal of again having 0.2.2 for this next wednesday.
@banagale Great that you picked up maintenance for this package. I use this in quite a few projects so I am looking forward to seeing Django 3.0 support.
So slow progress, thanks for patience from anyone paying attention.
I'm back on the project today. I got pypi maintainer permissions from Luke this past Tuesday, so I can actually push a release now. Going to work on 0.2.2 today.
@webconexus Thanks for the note. Hope we can have your feedback on the architecture changes for 0.3.
After reviewing the example project, I noticed that django-address began using Django 2.0's path, in the example project in March of 2018. Django 2.0's release required python 3.4 As a result, I am reversing my reversal to some extent: 0.2.2 will officially only support Django 2.2 and Python 3.5+ Additional notes here.
Okay, our first triage release 0.2.2 is ready for review.
All updates are in /release/0.2.2
I'm planning to submit this to PyPi as early as Monday, 5/9.
I'd appreciate any testing of the release branch that's possible. Particularly if someone can test Python 3.5 and 3.6 on Django 2.2 and Django 3.0.
It remains a future goal to have robust CI on this project.
Release Notes:
- Fix for
Noneissue preventing normal use of the project. - Fix for
on_deleteissue that impacted Django 2.2 and Django 3.0 differently. (models.CASCADE was necessary but could only be used as a string in 2.2, but not 3.0) - Update to project readme's stated requirements, project status and formatting.
- Update to setup.py to bump version and enforce updated requirements.
- Update to Example Site project interface
- Rework of Example Site readme to ease onboarding
Project Notes:
-
I'm moving the project to a standard
git flowstructure (more info), with a newdevopsbranch mentioned above. At this time, therelease/0.2.2branch anddevopsare the same. -
While I pulled two PRs, I'm still getting the hang of that and chose to manually incorporate some of the changes. I made notes in those PRs, acknowledging the work of the contributors.
-
The most important thing I found looking more deeply at this project was that it already required Django 2.2+ (and thus Python 3.5+) as noted above.
Thank you to everyone who contributed over the years to this from PRs, issues or just thumbs up in the issues and PRs addressed in this release.
Okay, django-address 0.2.2 is now on Pypi! I've also published as a release here on github.
Up next is 0.2.3, which is intended to focus on any remaining known bugs in the current package. 0.2.3 is intended to be the last update that uses the current model schema, which is to be updated and upgraded in 0.3.3.
My hope is to have CI testing in place with 0.2.3 among other improvements to the procedure and documentation of this project. That way we're in a good place to develop for 0.3.3.
For now, I'm keeping this issue open and moving it to 0.2.3.
I ended up getting caught in a project that ran a month over expectations and it prevented me from working django-address.
Over that time I worked with the package a bunch and and have thought more about how to proceed with development of this package. Here's where I'm at:
Keep focusing on improving django-address using the current model architecture as designed
Primary efforts:
- Find and remove bugs that still exist in the current package
- Modernize existing code base to use expected patterns
- Add code that assist in efficient retrieval of address information
- Improve documentation and examples to demonstrate common use cases
Delay Re-architecture of the package
I do believe that to accommodate so many different types of international addresses it is likely better to look at an abstraction that doesn't depend on the current Locality, State, Country model set. But perhaps something closer to the Administrative Area concept Google uses in its geocoding API respones.
However, there are a lot of people who are actively using this package as is who would benefit from incremental improvements listed above first. And we would want to have 1, 2 and 3 in hand before a re-architecture anyway.
I'm looking to do a minor release today to pypi, but am otherwise 'resetting' the milestones to be out another two weeks. And hopefully get into a repeatable drumbeat on releases.
I went ahead and released 0.2.3 to pypi and here, which is a severely abridged version of what was originally planned. It primarily resolves #111 and #108, a typo I made in the past release.
I also removed the assertion that made specification of a Google API key mandatory to just run the example app. I had previously added a state that gives visual feedback of the missing api key rather than erroring the user out.
I laundered the tickets for this release, which is ideally 7 days out. Heavy focus is on closing bugs that were reported long ago.
To help set priority, I added labels to the project as described in #101
Please feel free to jump on a ticket and submit a PR. Otherwise, release testing around the start of July would also be helpful.
Wow, I think this is the first release that has gone out earlier than scheduled!
django-address 0.2.4 is now available here and via Pypi (pip)!
As keeping with my previous thoughts, my goal is to iterate more quickly to improve the existing application before attempting a major model re-architecture.
There is still plenty to do, and I've bumped a variety of issues from 0.2.4 to 0.2.5. See the 0.2.5 Milestone for the current to-do's.
One of my biggest realizations with this release is the major dependency on the now unmaintained geocomplete library. I've updated this included library which we are now essentially forked from. Details on this are here.
A major strategic initiative is to document or outline common use cases of addresses of this library. This will help improve documentation and ensure the tests and behavior expected from the package are available.
For example:
- This package uses many relations that can have expensive queries unless used carefully. Common data retrieval examples could demonstrate better examples for use in the app.
- This package is sometimes used heavily to focus on specific countries, i.e. United States, the United Kingdom or Luke's original intention, Australia. Showing specific examples of how data is mapped from these geographies into the existing model set would be helpful for people trying to create queries and display information.
Regarding project maintainership, I've improved the notes I've been working on in the repo wiki that outlines the release process. This includes both the release to Github and to Pypi for pip.
I was also accepted into the Github sponsors program, so I went ahead and added the sponsor meta to this project in case anyone feels like they want to sponsor my work. This is currently first and only open source project, and I am the sole active maintainer. If you have the scratch and want to sponsor me, I'd be thrilled.
Finally, I'm continuing to focus on process around PRs. My hope is that any PR always be attached to an explanatory issue. I did this in reverse for PR #112, adding Issue #120. The idea is to keep the problem description separate from code changes. This way comments on PRs can be focused on the specific programatic implementation and any meta to the problem being solved can reside in the corresponding issue.
Special thank you to everyone who created or reviewed issues or PRs for this release.
edit: I've updated the subject of this issue so it makes better sense pinned and renamed it from its previous "Proposed Pathway Forward and Call for Comments"
If you have a moment, please consider replying to the issue "How do YOU use django-address? Add Comment Here"
It would be great to hear from people following this thread about how they use the package. I've pinned this along with this renamed thread to the issues page.
Also a big thank you to @moritz89, my first ever github sponsor. Yay! Sending you good vibes moritz!
I pushed out this next release milestone, 0.2.5 out another two weeks. Have a deadline, and my birthday is coming up.
Just a quick update that I've had another project slow me down a bit and I've had to push the 0.2.5 milestone back twice now. I am still on the case!
One of the open tickets for this next release was getting automated testing working as an incremental effort to professionalize the package.
Part of my other project was getting CI/CD working on Github Actions.
After looking at the state of CI/CD I believe Github Actions the most practical and forward looking option for django-address.
I have Django tests using github actions working well on the other project, so I'm hopeful to add that here soon. That will serve as an extra nice open source part of this project.
If you'd like a preview of what I'll apply here, you can read the blog entry I published about this: Running Django Tests in Github Actions.
Hi @banagale, I've re-read the preceding comments again as you probably said this at some point, but couldn't find the plan of how many more minor releases the 0.2 series is going to get, before you go to 0.3 (and any idea of how far out that will be?) As you know I'm eager for 0.3 because that's where we can rejoin the mainline. The top priority feature for my site is going to depend on location, but I don't think I can roll that out until I get on a more stable version. Thanks for everything you're doing!
@jplehmann Thanks for checking in and the prompt regarding rejoining the mainline.
I can't say when we'll be ready to move from the present to a new model architecture. I am also unsure if the branch your site is based off will cleanly merge into that.
I can say that after learning so much about addresses at the start of the year I can better understand where Luke was coming from in his model abstraction effort.
My immediate goal remains to get the current schema into a better place, meaning better documentation and code cleanup before making that move.
I did see your update to your update to how you use the package. Can you give more information about the feature you want to release and how the existing abstraction in the dev branch is getting in the way of a clean build?
I am also unsure if the branch your site is based off will cleanly merge into that.
Totally understand and realize that there may be a significant effort on our part and am ready to bite that off and get it behind us.
Can you give more information about the feature you want to release and how the existing abstraction in the dev branch is getting in the way of a clean build?
Well, we have numerous "bug" issues in my project based on the django-address dev branch. The errors we get may be code bugs or they may be corrupt data which was caused by previous bugs. At 30k feet, it looks like a user trying to autocomplete to some location, and getting an error. Our workaround is to apologize and tell them to choose a location nearby and that usually works. This works when it happens maybe once a week and they are determined enough to try again.
This problem seems to happen less frequently than it used to, however we only expose the autocomplete to a fraction of our users (the sellers). The feature work we are doing is to introduce a proximity search for all users -- filter my search to all items within X miles/km of my location. This means we'll be using the autocomplete feature 2 orders of magnitude more often, and what was an infrequent problem will become very frequent.
Rather than dig through these bugs and try to figure them out in this deprecated version we are using, which seems like a waste of time, I thought it would be better to get back on the mainline in 0.3, and see if we were still having problems. This is why I was eager to rejoin sooner than later.
It is possible we can use a browser location function to get the user's location in which case we may not need the API as much; I'm not sure if that provides lat/long or we still have to look it up.
An alternative is that we don't wait until 0.3, and we ditch the dev branch and figure out how to go straight to the current 0.2x mainline but in that past I believe you recommend we wait.
In case anyone's online and interested, I'm live streaming work on django-address right now: https://www.twitch.tv/happybuilding. edit: offline now. Made some good progress, should have #50 and #82 sorted and hopefully a release tomorrow.
Going live again now to finish up these tickets and complete the release. Come say hi if you're online. :)
Okay, 0.2.5 is in master and resleased to pypi (pip). I'll post release notes soonish.
Version 0.2.5 is now released to Pypi and Github. Release notes are:
Summary of project updates:
- #123 - Added documentation on how to run project tests
- #125 - Added Github Action-based automated testing (see recent results)
- #125 - Investigated and removed outdated test
- #50 - Update State model to allow for Mexican state codes longer than two characters
Additional results from this release:
I am working on some live streaming software in another project. To learn more about the live streaming experience I started live streaming my work on this project. I do not know if I will continue to do this or not, but it was an interesting experience.
I've made a number of PRs on other projects since the last django-address release and have realized that now that this project is out of triage mode changes should be following a more consistent pattern of contribution from maintainers, i.e. me. So I'll hopefully no longer be committing to develop directly going forward and will document the requested pattern in my completion of #128.
I spent considerable time coming to understand the problem with US territories and documented a lot in both #82 with some notes in #50. This turns out to be a political issue to some extent, I'm encouraging anyone with feelings about how to discuss this / how it should be programmed to step forward. Particularly those who live in Guam, Puerto Rico or any US territory.
Hi @banagale, I'm from Puerto Rico and yes we usually have a hard time dealing with addresses, I have seen a lot of combinations in terms of how websites/companies deal with PR. Sometimes Puerto Rico shows up as being a State of United States, others as a Country and I've also seen it in both at the same time. In google it shows up as country in the address_components. Seeing the schema of this project and as a personal preference I would deal with PR as a state of United States because for me it will not make sense to add the cities/towns of PR as being States of PR.
Taking Amazon as an example. I can add my home address using either United States or Puerto Rico and both will work.
Hello. Putting in some time on django-address now.
Come say hi in the Livestream on Twitch
Wrapping up work for this session now. Had a few folks from this thread drop into the livestream and got to "talk" with them. Was really cool. Thanks a lot for saying hi.
Also got a little work done. :) Largely administrative but clearing PRs out was probably the most important. That said, not enough code changes to justify a release, so I've pushed 0.2.6 out.
Next session I'll hopefully resolve #82 and testing stuff.
Streaming work on django-address now: https://www.twitch.tv/happybuilding
Just a quick check-in. I've had a fair amount of professional work that's slowed me down on DA for a bit. I have also been making some open source contributions in other projects. Fortunately, I have picked up some tricks which I'm hoping to bring back to add value here.
For now, things seem largely stable. I do want to get this US territory code in as soon as possible, though.
Wanted to get an update ITT to recognize the recent contributions of the package's author, @furious-luke!
Luke's been helping stay on top of PRs and handled a number of chores that have been accumulating.
Thank you, Luke!
@furious-luke is back and he's coding in ANGER!!!!
@banagale @furious-luke is it possible to get a patch release?
I just encountered #130 which was fixed back in Sept 2020 and it looks like there has not been a release since. Happy to install via another method other than pypi if there is something I am missing.
Hey @adamduren ! Sure thing, I'll cut a release today. Cheers!
Sweet, thank you!
Sorry for the delay @adamduren, just pushed out 0.2.6.