Development Quick Start

This page describes how to develop a DjangoCMS app.

• applicable to any Django project
• originally intended for https://github.com/TACC/Core-CMS (large proprietary project)
• testable via https://github.com/wesleyboar/django-cms-quickstart (small community project)

0. Use This Repo Template

Follow GitHub documentation.

Details (for a TACC/Core-CMS Django app)

1. Match the repository naming pattern: Core-CMS-______ (for websites) or Core-CMS-Plugin-______ (for plugins)

   Guidance

   For websites, the ______ should match the "App Name" if it has no spaces (e.g. "Frontera", "UTRC", "A2CPS"). Do not replace spaces with dashes (dashes would undesirably allow parts of the website the name to be interpreted as a hierarchy).

   For plugins, the ______ may match the "App Name" if it has no spaces (e.g. "Callout"), or the "App Name" with dashes for spaces if the name has an adjective re-usable for other plugins (e.g. "System Monitor", "System Specs").

2. Describe the the repository using this template:

   For websites, "The website for ______".
   For plugins, "A DjangoCMS plugin (for TACC/Core-CMS) to ______".

3. Use relevant Topics (tags) from this template repository:

   tacc, django, django-cms, (if a website) website , (if a plugin) django-cms-plugin

4. Include the same features on the home page as this template repository:

   • Releases

1. Update the README.md Introduction

Complete the README.md's heading, description, and formatted names.

Details (for a TACC/Core-CMS Django app)

Django CMS [Website|Plugin] (for TACC/Core-CMS): "App Name"

This [website|plugin] [provides something].

• __dist-name__: djangocms-tacc-the-example
• __package_name__: djangocms_tacc_the_example
• __ClassName__: TaccsiteTheExample
• "App Name": "The Example"

Details (for any Django app)

Django (optional_scope_of_project): "App Name"

This [app|website|plugin] [provides something].

• __dist-name__: django-tacc-the-example
• __package_name__: django_tacc_the_example
• __ClassName__: TheExample
• "App Name": "The Example"

2. Rename the __package_name__ Directory

The name should match the __package_name__ value (from README.md).

3. Update setup.py's setup() Arguments

1. Update placeholder values to be accurate to your website/plugin.

   • name = (__dist-name__)
   • description = (the repository description)
   • url = (the repository URL)

2. Add any relevant classifiers. For options, https://pypi.org/classifiers/.

   • The License :: OSI Approved :: … must match the LICENSE used. For help, see section 6.

4. Update requirements.txt Dependency Versions

Details (for a TACC/Core-CMS Django app)

For websites:

• do add taccsite-cms dependency and version appropriately﹡

For plugins:

• for dependencies shared with Core, you may reference TACC/Core-CMS:pyproject.toml for versions
• avoid taccsite-cms dependency unless necessary; and, if so, then version appropriately﹡

﹡ Get version from https://github.com/TACC/Core-CMS/releases (minus the v) until proper Python-based version exists.

Details (for any Django app)

For websites:

• do add any CMS dependency e.g. django-cms and version﹡

For plugins:

• for dependencies shared with another project, you can reference that project's pyproject.toml for versions
• avoid excess dependencies

5. Update MANIFEST.in Dependency Versions

• Change __package_name__ to the name of the directory that has your app's files.
• Remove/Add entries to accurately define what must be in the distribution. For help, see Python's guide.

6. Update apps.py Names

Change the following names to the correct name based on your project's README.md:

• __package_name__
• __ClassName__
• App Name

7. Confirm the LICENSE & Copyright

Note

After more research, this step should be updated or removed.

Resources

• https://guides.lib.utexas.edu/copyright/implementpolicy
• https://research.utexas.edu/otc/for-inventors/software-open-source-copyright-licensing/
• https://www.utsystem.edu/offices/general-counsel/intellectual-property
• https://www.utsystem.edu/documents/docs/general-counsel-documents/2010/software-standard-agreements

8. Document Your App via the README.md

In the README.md, update everything after "Quick Start" step 1 to be specific to your app.

Warning

Be sure to review, and use or edit or remove, any example content (so you do not confuse users).

Tip

For websites, under "Features", list any customizations your website makes to Core.

9. Test Your App & Request a Review

You may use https://github.com/tacc-wbomar/django-cms-quickstart to test (example) and request a review.