In thinking about our guidebook and tutorials and the question @jagerber48 had around building, i started to work on a conceptual diagram that shows the entire process. we can then create sub diagrams to focus in on specific areas.
the colors and graphics aren’t close to final but i welcome ANY IDEAS on the conceptual idea, what’s missing, what’s confusing, what you like, etc. many thanks in advance. i think one thing immediately i’m seeing is the fonts are too small but i can work on graphics more once we all agree it’s a good approach!!
1 Like
This graphic is super helpful! Definitely breaks down key major and minor components. I’m curious about the “Check build and publish” item. Seems like “Check build” is covered by run formatters/linters/tests and then “publish” is actually the content of the large arrow and boxes to the right?
At a higher level: I wonder what the similarities and differences are between the bottom “Local Development Workflow” bubble and the top “Contributor Local Workflow” bubble. It sounds like the contributor bubble is more about the workflow for casual contributors to some package (engaging in issues/discussions, maybe writing some code and PRs) whereas the “local development workflow” is more targeted towards more dedicated contributors like authors or maintainers who have additional responsibilities like approving PRs and making higher level steering decisions about the package. I do like the arrow going to the Contributor local workflow bubble. I like that it highlights the importance of how a “package” interacts with the community and vice versa.
2 Likes
hey @jagerber48 thank you for this feedback. let me try to explain what i was trying to show - and then maybe you can tell me what could make it more clear!!
Seems like “Check build” is covered by run formatters/linters/tests and then “publish” is actually the content of the large arrow and boxes to the right?
So - this is specific to how i like to set things up. let’s see if others agree! When i / our maintainer team thinks about publishing we like to have a way to test the build before using PyPI. So what happens is that any PR that is merged into main runs a build of the package, imports it to ensure no errors and then pushes to test-pypi where we can install and test again from test-pypi IF we want to. This just ensures that something funky didn’t happen with that pr / set of commits. so that is our pre-publish check step which i wanted to capture with that language.
But your point about publish being on the left but the actual publish pipelin is on the right - that’s confusing!! I’ll fix that.
It sounds like the contributor bubble is more about the workflow for casual contributors to some package (engaging in issues/discussions, maybe writing some code and PRs) whereas the “local development workflow” is more targeted towards more dedicated contributors like authors or maintainers who have additional responsibilities like approving PRs and making higher level steering decisions about the package.
ok i was hoping this was clear but wasn’t sure. I wanted to somehow communicate that exact point that - you might have a maintainer or maintainer group who develop documentation, dev guides, contributing guides, etc. That infrastructure and documentation then supports building community around the project and other contributions. BUT the contributor workflow may be very similar if not almost identical to a maintainer - with the exception of being able to merge prs, etc etc.
but the idea of the central online repo being the hub that facilitates that interaction between contributors maintainers and the code/docs.
this feedback is super helpful! thank you. i’ll work on it a bit more today and will post a new version along with the text i worked on based upon that issue discussion we all had.
Here is an updated diagram with a bit more refinement.
here is the document with the new text answering the question - “what is building” open to feedback / comments on both. feel free to comment in the document if you want to suggest changes, etc.
And i’m open to ANYONE’s and everyone’s feedback here !!
I wonder if “Contributor local workflow” might be better as “Contributor workflow”? It’s not really local as all the things you mention are typically done through web services. And the Local Development Workflow is equally for contributors as it is for maintainers. To me, this reads as a split between project management and technical development.
I think the local workflow should include running linters and type checkers. This could be under the write tests or its own section TBH. Style changes are going to be fixed locally, so it’s always nice to not have to push to a remote git just to check for a linter pass/fail.
Another local workflow addition would be to locally serve docs. IMHO anything CI does should also be easily possible in a local environment, so long as the work stays on the machine.
1 Like
Ok - this is all great feedback - thank you!! and also if you tried to get into that google document and couldn’t- i just fixed the permissions (i think). i’ll create another version of the graphic and post here in the next day / early next week!!!
Hm, is it normal when I click to enlarge the first image that it gets a black background? I was trying to see it in details but that way I couldn’t read the text 
.
Btw, I also agree with @ ucodery, I think “Contributor Local Workflow” could be better as just “Contributor Workflow” and I would say the same goes for “Local Development Workflow” => “Development Workflow”. The graph looks overall really pretty 
. Another suggestion I have would be to have an even higher-level version of this because in a first look it is already very detailed and can be a little scary.
1 Like
such great feedback!!
@arianesasso based on what we worked on today - here is the current state of both graphics!!
More complex detailed example - this might go on our packging guide landing page?
The simpler version that is on the new build section of the guide.
