beeware / beeware/briefcase

Add a guide for converting an existing project

Open
#1,961 0 comments 0 reactions 0 assignees View on GitHub
documentation enhancement
Dominant language
Python
Stars
3.3k
Forks
549
Avg merge
1d 4h
Merged PRs (30d)
40

Description

### What is the problem or limitation you are having?

With the introduction of Briefcase's Convert command, it is now even easier to support adding Briefcase to existing projects. However, the conversion process makes assumptions and puts requirements on the state of the project to be converted; so, when errors are encountered during the conversion, it may not be obvious how to handle them.

Especially with support for console apps, it seems reasonable that more devs will approach Briefcase as a post-hoc packaging solution for apps that only run in the console.

### Describe the solution you'd like

Add a how-to guide for converting an existing project to Briefcase. While I think the guide should help readers to understand how a Briefcase project is structured, I also think it should be somewhat of a checklist to help make sure the conversion will be optimal.

### Describe alternatives you've considered

n/a

### Additional context

Related:
- https://github.com/beeware/briefcase/issues/1897
- https://github.com/beeware/briefcase/issues/1898
- https://github.com/beeware/briefcase/issues/1899
- https://github.com/beeware/briefcase/issues/1900
- https://github.com/beeware/briefcase/pull/1958

Contributor guide

Open the contributing guide

Research direction

Start with Briefcase's Convert command and the related issues 1897–1900 and pull request 1958 to understand the conversion assumptions and known errors. The guide is done when it explains Briefcase project structure and provides a practical checklist for converting existing projects, including console apps and handling conversion errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.