Skip to content

[Feature Request]: Reorganize the Project Setup Documentation #5099

@adhiamboperes

Description

@adhiamboperes

Is your feature request related to a problem? Please describe.

Many new contributors run into issues setting up the project, especially on a Windows SDE. Having run tthrough the setup instructions myself, I noticed that while all the information needed to setup is present, a bit of reorganization would be useful to minimize skipping some important setup steps, which will in turn minimize the number of reported setup issues.

Some problems I noticed with the current instructions are:

  • The main setup page contains instructions for setting up the development environment for all the OSes together with a number of external links. This means contributors have to keep going back and forth between tabs, and may lose their place, which often results into skipping steps.
  • The current setup steps advise to install the latest Android Studio version, but our project does not support the latest gradle versions bundled with newer IDE versions.
  • Steps 2 and 3 of the setup instructions involve setting up Java 8. This is not an actual pre-requisite to getting the project running, yet it is a non-trivial task. Android Studio comes with its own embedded JDK, and it is possible to install additional versions from within the IDE if needed. Our project can build on gradle with JDKs 8-11, which are sufficient for getting started on a first issue.
  • In relation to the JDK step above, there are missing instructions on specifying the compile jdk version from within Android studio --- even if you set the java home variable, Android Studio defaults to its embedded jdk.
  • Most contributors never run the bash setup.sh command, missing out on important pre-push checks.

Describe the solution you'd like

I do think that, pre full bazel migration, we should allow our contributors to get started with just gradle as this lowers the barriers to start contributing. Most of the starter issues for the foreseable future do not need interaction with Bazel.

Some changes we can make to improve the setup Wiki:

  • From the onset, split the setup instructions per OS. This means that the first page of setup instructions will have a format like this:
     - Select your operating system to get the setup instructions:
        - Linux
        - Windows
        - MacOs
    

Then on each OSs page, we will have the complete OS specific setup instructions, numbered.

  • Update the required Android Studio Version instructions to Bumblee Bee Patch 3 (direct download url)
  • Move the Java 8 and $JAVA_HOME setup instructions to the Bazel set up section on each page, since they are only relevant there.
  • Add instructions on how to select the compile JDK from within Android Studio Settings.
  • Update outdated instructions related to SDK path in Android studio and that of downloading the google files check file.
  • Include a post-setup checklist to verify all the setup steps have been completed.

Describe alternatives you've considered

  • Adding instructions about common set up issues, their causes and how to fix them.

This option is reactive rather than preventive.

We can still however have a section for this, especially for issues that cannot be prevented such as #4966 (comment).

Additional context

#5061

#4858

#4432

Metadata

Metadata

Assignees

Labels

Impact: HighHigh perceived user impact (breaks a critical feature or blocks a release).Work: MediumThe means to find the solution is clear, but it isn't at good-first-issue level yet.enhancementEnd user-perceivable enhancements.

Type

No type

Projects

Relationships

None yet

Development

No branches or pull requests

Issue actions