Long-term notes

[ehmatthes]

The deployment landscape is constantly evolving. There are a number of approaches to automating deployment, and it's not always easy to know what the stability of any one approach is. For example, Heroku has been moving away from classic buildpacks for a while now, but not very quickly. (See here for a long thread on adding Poetry support to Heroku.)

This is a collection of thoughts about possible directions to go. All of this is in line with the original intent of this project - hide the messiness and instability of deployment processes from developers of relatively simple Django projects as much as possible. When deployment processes change, update the internals of this package rather than changing developers' workflows.

[ehmatthes]

• If setting a specific buildpack is the best approach, simple_deploy can do that.
• If the deployment process changes, and simple_deploy was used for the original deployment configuration, it may be able to update the project configuration for the new deployment process.

[ehmatthes]

This should probably be restructured as an entry under docs/.

[ehmatthes]

Misc

• Consider using color for output.
  • See Consider using Rich #70, but also see syntax coloring and BaseCommand.style in Django docs.
• Is there anything under testing Management Commands in the Django docs that I'm not currently using?
• Make output and output_obj consistent.
• Make error message more informative when no requirements are found, in _get_dep_man_approach(). State that we're looking for requirements.txt, Pipfile, or Poetry use.
• Clean up all the skip_logging arguments.
  • We can probably set a self.started_logging flag, that starts logging once all validation has been completed.
• Consider logging both stderr and stdout by default.
  • For example, create command writes to both stdout and stderr. On successful run, project id to stdout and all other to stderr.
• Consider logging some of the initial output once logging starts.
  • At the very least, make sure the original command is logged.
• Add 'Returns:' section to all docstrings.
  • simple_deploy.py
  • deploy_platformsh.py
  • deploy_heroku.py
• Be consistent about using msg in general cases, and error_msg when preparing exception messages, ie when raising CommandError.

[ehmatthes]

Testing

• Test that an invalid command, ie omitting --platform flag, does not create a log dir.
• Unit test invalid versions of simple_deploy command.
  • Perhaps make a version of call_simple_deploy.sh that makes a series of invalid calls? Maybe this would be a .py script that makes these calls, and then examines output? That would be more in line with pytest.
• Test that an unclean git status errors out; see _check_git_status().
• Unit test Platform.sh' project name inspection process? See Recommend users to call platform create before running simple_deploy #94.
• For integration tests (e2e), verify sections of the log that don't show up in unit tests.
• For integration (e2e) tests, conftest.py.check_valid_call() should check that the CLI is installed and authenticated.
• When running integration (e2e) tests, it's not uncommon for final functionality tests to fail due to inconsistent delays in the site actually being available. Before destroying project, consider writing the command that would run the final functionality test to the console. The user can then copy that command to a separate terminal tab, and run the functionality tests once the site is ready.
  • These full deployment tests should have a retry loop, and a timeout that can be passed.
• I believe the skipped tests in test_project_inspection.py can now be implemented, with logging in place.

[ehmatthes]

Documentation

• Mention option of confirming preliminary support status of a newly-supported platform in supporting_platforms.md. Link to a current or previous file with this confirmation, ie deploy_platformsh.py.

[ehmatthes]

Conventions

• Establish a clear line length convention.
  • Use Black?

[ehmatthes]

Manual (one-off) tests

• I have a Platform.sh account, so it's hard to test the workflow for automate_all when the user is logged in to the CLI, but has no organization.
  • Test this, perhaps by destroying my organization when I have no active projects.

[ehmatthes]

--docs flag

• Create a --docs platform_name flag, that will list the main entry points to that platform's docs as they relate to Django, and Python in general.

[ehmatthes]

Platform.sh deployments

• Is there any way to show progress during project create?
• Any way to show progress during project push?
• Refactor code that checks output of CLI commands.

[ehmatthes]

Developer support

• Consider more developer-focused flags.
  • For example, a --no-deploy flag might help when modifying the simple_deploy.py script. A block that exits just before deploy() is called, if this flag is set, would prevent any changes from being made to the test project. This saves some git checkout ., git reset, and rm calls.

[ehmatthes]

• Support wagtail deployments. See Try deploying wagtail #173.

[ehmatthes]

Ensuring safe modifications

I've always been uncomfortable with the failure modes when simple_deploy can't finish its work after starting to make changes to the project. It's not a terrible situation, because people need to be using Git already, and we check for a clean status. But it still doesn't feel right to start making changes and then maybe have to bail on the user.

• Consider moving to a model where all changes are prepared in memory, and then only written to the user's project when we know that all necessary changes are ready. This is a more complicated approach, but should reduce significantly the number of projects that are left modified without being ready for deployment.
  • First thoughts at implementation: write all files to a temp dir, then copy to the user's project when we know there are no breaking issues.
  • Could start implementing this with logging.

[ehmatthes]

Logging

• Make sure all commands that are being run are logged. I believe some commands only have their output logged. See Simplify logging #260.
• Also from Simplify logging #260: Note for later that much of this logging could be moved to ie execute_command(), or execute_subp_run(). Would probably need skip_logging parameter.
• Some multiline output is not broken into lines. Make this consistent.

[ehmatthes]

General

• Some of _confirm_automate_all() should be moved to either simple_deploy, or maybe even utils.
  • Or a parent class?
• Note: further refactoring could break simple_deploy.Command up into a class that handles package management issues. But the plugin model is higher priority. (Agreed, not now.)