Improve documentation for contributing to an existing app

[mattcen]

Existing documentation doesn't make it quite clear what set-up is required to configure an environment to contribute to an existing Beeware application, so it took me a while to work out which commands to run (what I was missing was that I needed to run briefcase dev with the -d flag to install toga and any other dependencies.

I don't have the capacity to work out where best to put this documentation myself right now, but the quick bit of documentation I just wrote for my own project is below for reference:

---

Getting a dev environment up and running

1. Clone this repo:

   git clone [email protected]:your_username/your_repo_name.git
   

2. Create a Python virtual environment:

   python3 -m venv beeware-venv
   

3. Activate the virtual environment:

   . beeware-venv/bin/activate
   

4. Enter the project directory:

   cd your_repo_name/
   

5. Install Briefcase in the virtual environment:

   python -m pip install briefcase
   

6. Run your project in your dev environment. Note that the -d flag to briefcase dev is required the first time around to install missing dependencies that are specified in pyproject.toml:

   briefcase dev -d
   

[freakboy3742]

Thanks for the suggestion. I'm not sure how/where this would fit into the BeeWare tutorial, but if we can do something to clarify the process of sharing a project with others, we should definitely do so.

Regarding the specific steps though - I'm surprised -d was needed. This suggests that the project you were sharing had put the macOS/windows/etc platform folders into version control. This points to another gap in the tutorial - the platform folders should generally be considered "build products" and be in .gitignore, rather than a shareable artefact. If those folders were not in version control, your first step would have been to run briefcase create, which would have installed the requirements (removing the need for -d until a later update).

So - maybe we need an additional step in the tutorial on sharing your app which covers what should be in version control when you share your project; and how someone else would use your project.

It might also make sense for the briefcase app template to include a .gitignore file that excludes the build product directories, and generate a README that includes stub "how to clone this project" instructions.