flutter
[proposal] simplify procedure for updating code samples on flutter/website
this issue is entirely based on my personal opinion
Attempting to fix this issue I submitted for the first time a PR for flutter/website (that may or may not be successful)
and followed these docs
I feel that the current steps required for producing a PR is:
- overly complex there are at least 9 steps completely unrelated to the actual code change
- bloated that require the local installation of
- flawed following to the letter some steps output errors, only in part fixable by the contributor (and very many warning)
you can find the details in this comment
expectation
the steps for providing a PR should be
- clear
- streamlined
- leave the contributor's machine as clean as possible
- does NOT constitute a barrier for contributions
actual
I feel the steps for providing a PR are
- complex
- require many actions unrelated to the actual contribution
- leave the contributor machine bloated with unwanted software
- most importantly a strong deterrent from submitting a PR
@iapicca , I agree that installing all the tools needed to stage the Flutter website is a long process. However, it is a necessary one, as that is the only way to properly stage the Flutter website locally. I'd like to bring up a few points:
-
It is not necessary to install all these tools for the vast majority of PRs. Many PRs require simply editing Markdown files, and perhaps some testing of code within an emulator. Fewer PRs require staging the site.
-
Generally, PRs that require staging the site could be considered more difficult; those that require more expertise. That means usually, people with experience in the flutter/website repositories deal with these issues. While your contribution was important, I think your case is rare, as you took on one of these difficult issues in your very first PR.
-
Additionally, most developers that have the expertise to work on difficult issues generally continue contributing to flutter/website. You treat staging the website as steps 1-9, and making your PR as step 10; consider that many developers don't consider this process "overly complex" or "bloated" because they are fine installing these tools over a long period of time. Developers might also already have many of these tools because these are also useful tools for many kinds of projects.
Again, I agree these steps are complicated, but ultimately it's the process necessary to make major changes to the flutter.dev.
Lastly, I am very interested in this line:
following to the letter some steps output errors, only in part fixable by the contributor (and very many warning)
Can you specify which steps you are referring to here? Ironing out any errors from the guide might be the best way to simplify the process for the future.
Can you specify which steps you are referring to here? Ironing out any errors from the guide might be the best way to simplify the process for the future.
@micpap25 following the link I provided above
you can find the details in this comment
all these steps output an error
- run before-install.sh FAILED!
- run install.sh
- run tool/refresh-code-excerpts.sh
moreover
- It is not necessary to install all these tools for the vast majority of PRs. Many PRs require simply editing Markdown files, and perhaps some testing of code within an emulator. Fewer PRs require staging the site.
nevertheless, simply updating a code sample requires the steps I mentioned probably the title of the issue is misleading, I'm updating it
casually browsing the issues in this repo it's easy to notice that many of those are request to update or fix code samples; maybe this is the case because, developers are not submitting PRs due to the complexity of the process
- Generally, PRs that require staging the site could be considered more difficult; those that require more expertise. That means usually, people with experience in the flutter/website repositories deal with these issues. While your contribution was important, I think your case is rare, as you took on one of these difficult issues in your very first PR.
requiring expertise in the flutter/website repository just to fix a broken code sample it's the core problem; consider the possibility that my case might be rare because potential contributor don't submit PR due to the complexity of the process
3. Additionally, most developers that have the expertise to work on difficult issues generally continue contributing to flutter/website. You treat staging the website as steps 1-9, and making your PR as step 10; consider that many developers don't consider this process "overly complex" or "bloated" because they are fine installing these tools over a long period of time. Developers might also already have many of these tools because these are also useful tools for many kinds of projects
this seems a very iffy assumption and it should not be a given,
but even so I could understand, downloading nvm, rvm, node and ruby,
while the need for downloading an additional copy of flutter is still inexplicable for me
the instructions provided are fairly easy to read, but outputs errors (at least in my case, see above) I have 3 proposal in ascendant order of both likability and complexity:
-
a script
- safely set up the environment in a testable manner
- (might) prevent errors of the likes I'm experiencing
- another script to remove the "potentially unwanted" software could be provided
-
a docker image
- always up-to-date
- works everywhere
- easily to delete when not needed
-
a github-action
- always up to date
- effortless process for the contributor
- (maybe) it could cache the set-up
I have to be honest, I kinda agree with @iapicca. Setting up Node and Ruby on my workstation so that one can work on a Dart product's web site seems excessive. I've personally avoided doing this for the entire length of the project, instead relying on CI to catch problems I introduce, which isn't a great experience either.
I do want to preface all this by saying, I'm not a Google employee or affiliated with Google; I just do a lot of triage on Dart and Dart-related repositories. I'm also sorry if I'm coming off as anti-progress, I'm trying to play devil's advocate a bit because I want to make sure the simplification gets to the root of the issue.
while the need for downloading an additional copy of flutter is still inexplicable for me
I'm a bit confused where the instructions say to install a second copy of Flutter; it says that you need to have Flutter, but only need to download it if you don't have it already. Can you specify which line says this?
a script
I agree that a script could be a compact way of installing all requirements, though it wouldn't solve the bloated issue you bring up.
a docker image
I don't agree as much with this, as this would require installation of Docker, which would be another step that would work against reducing complexity and bloat.
a GitHub action
I'm not too familiar with GitHub actions, so I'm not going to comment on this.
I think I'm going to step out of this issue and let people with more experience and control than me handle it. Hopefully a solution can be arrived at.
while the need for downloading an additional copy of flutter is still inexplicable for me
I'm a bit confused where the instructions say to install a second copy of Flutter; it says that you need to have Flutter, but only need to download it if you don't have it already. Can you specify which line says this?
@micpap25
it's in the same logs I provided in the PR's comment under the collapsible run before-install.sh FIXED!
I can assure you that I had the master version of flutter already installed under fvm
Hi, @Hixie, @micpap25, @iapicca! This is why we now use a Docker instance for staging the site. To make it an easier process. Please let us know if you still find it to be a bloated/awkward experience.
@sfshaza2 looks definitely better now! Unfortunately I don't have much time to try at the moment, but I can give it a shot in the future. my 2 cents: if some GDE / influencer / youtuber would make a video about this I bet that all the code sample on the website will be up to date in no time
I really appreciate the effort to provide a better experience for contributors
@iapicca, thanks for that last comment! And, yes, that is a great idea for a video. I'm going to add it to our (internal) suggestions page.
@iapicca : Did this change meet your needs? Let us know if further action is needed. Thanks!
I don't have the bandwidth to check this right now, closing as solved, please reopen if you feel that something else needs to be done