Add a guide for converting an existing project
- 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
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