diff --git a/docs/developing/extending/creating-apps.rst b/docs/developing/extending/creating-apps.rst index 4e20aa3..225279d 100644 --- a/docs/developing/extending/creating-apps.rst +++ b/docs/developing/extending/creating-apps.rst @@ -2,47 +2,71 @@ Creating Applications ##################### -Starting with version 7.5, Arches moved to a new architectural pattern to support certain customization needs. This new pattern called **Arches Applications** (alternatively **Arches Apps**) should make customizations easier to develop and maintain. This architectural pattern also aligns with standard Django practices for the introduction of reusable sets of new features. +Starting with version 7.5, Arches adopted a new architectural pattern to support the need for implementors to easily share and maintain custom code. This new pattern, called **Arches Applications**, is similar to using "installed apps" in Django. It allows for easier development and maintenance of custom features by aligning with standard Django practices. -What's an App? -============== -The phrase **Arches application** (or **Arches app**) describes a Python package that provides some set of features added to the core (standard) Arches application. Arches apps can be reused in multiple Arches projects. This terminology about *applications* and *projects* purposefully aligns with the `Django definition and use of these terms `_. +What's an Application? +====================== +The term **Arches application** describes a Python package (usually pip installed) that provides some set of additional features beyond what core Arches provides. Arches application can be reused in multiple Arches projects. + +Applications typically include some combination of models, views, templates, static files, URLs, etc. They’re generally wired into Arches projects with the INSTALLED_APPS setting. .. figure:: ../../images/dev/diagram-custom-apps-in-projects.png :width: 100% :align: center - Illustration of Arches projects integrating custom Arches Apps. + Illustration of Arches projects integrating custom Arches Application. + + +When are Arches Applications Useful? +==================================== +Arches Applications are a means to power special purpose features that may not be appropriate for incorporation into the core (standard) Arches application. A given Arches Application can be under version control independent of core Arches. This should make it easier to update, upgrade, and maintain a custom Arches Application independently of Arches core. + +Just like Arches itself, an Arches Application can also be developed, shared with the public, and be made open source. This means that the custom features powered by an Arches Application can be reused widely across the community. Because Arches Application development can proceed independently of core Arches, Arches Applications can be an excellent way for community members to experiment with features beyond those listed on the official Arches software development roadmap `official Arches software development roadmap `_. + +`Arches for Science `_ illustrates the value of Arches Applications. Arches for Science has several workflows and features (together with additional software dependencies) useful for cultural heritage conservation science. However, these features would be unnecessary for many other core Arches use cases. Keeping these conservation science features in a distinct application allows `Arches for Science software development `_ to continue at its own pace, and it reduces pressures to add highly specialized features to core Arches. Arches Applications can therefore help reduce the complexity and maintenance costs of core Arches. + + +Arches Applications Can Help Avoid Forks +---------------------------------------- +Arches Applications allow you to add special features to an Arches instance without forking the core Arches code. Avoiding forks has several benefits, including easier maintenance and the ability to apply upgrades and security patches provided by core Arches.``` + +A given Arches Application can also be developed and shared open source. This means that the custom features powered by an Arches Application can be reused across the community in multiple Arches projects. + + +Developing an Arches Application +------------------------------ +While any given Arches Application can be reused in multiple Arches projects, one must first create an Arches project to host the Arches Application you seek to develop. You start with the following command to create a new Arches project to host your Arches Application: +.. code-block:: shell -When are Arches Apps Useful? -============================ -Arches Apps provide a means to power special purpose features that may not be appropriate for incorporation into the core (standard) Arches application. A given Arches App can be under version control independent of core Arches. This should make it easier to update and upgrade core Arches independently of a custom Arches App (and vice versa). + # Create a new Arches project for your Arches Application "example_app" + arches-admin startproject example_app -A given Arches App can also be developed and shared open source. This means that the custom features powered by an Arches App can be reused widely across the community. Because Arches App development can proceed independently of core Arches, Arches Apps can be an excellent way for community members to experiment with features beyond those listed on the official Arches software development roadmap `official Arches software development roadmap `_. -`Arches for Science `_ illustrates the value of Arches apps. Arches for Science has several workflows and features (together with additional software dependencies) useful for cultural heritage conservation science. However, these features would be unnecessary for many other core Arches use cases. Keeping these conservation science features in a distinct app allows `Arches for Science software development `_ to continue at its own pace, and it reduces pressures to add highly specialized features to core Arches. Arches apps can therefore help reduce the complexity and maintenance costs of core Arches. +Arches Applications will sometimes require specific versions of core Arches to function properly. Therefore, their maintenance and upgrade paths should be carefully considered. In addition, different Arches Applications may have different dependencies (including other Arches Applications), which can complicate future upgrades. Finally, Arches Applications may require additional testing to ensure that they are compatible with Arches Applications and with the core Arches software. In creating an Arches Application, you can specify version information and version expectations for core Arches in the ``settings.py`` file of your application. +.. code-block:: python -Arches Apps Can Help Avoid Forks --------------------------------- -Through Arches apps, desired special features can be added to an Arches instance without forking the core (standard) Arches application code. There are many advantages to avoiding forks of the core (standard) Arches application code. By avoiding forks, one can more easily take advantage of continued upgrades and security patches applied to core Arches. This makes your use of Arches easier to maintain and secure. + APP_NAME = "example_app" + APP_VERSION = semantic_version.Version(major=1, minor=0, patch=0) + APP_ROOT = os.path.dirname(os.path.abspath(inspect.getfile(inspect.currentframe()))) + MIN_ARCHES_VERSION = semantic_version.Version(major=7, minor=5, patch=0) + MAX_ARCHES_VERSION = semantic_version.Version(major=7, minor=6, patch=2) -A given Arches App can also be developed and shared open source. This means that the custom features powered by an Arches App can be reused across the community in multiple Arches projects. -Getting Started with Arches Apps -================================ -The Arches team created a simple example Arches app to illustrate how to develop and deploy custom apps. The example app called **Arches Dashboard** displays a summary count of resource instances and tiles in a given Arches project. +Getting Started with an Example Arches Application +================================================== +The Arches team created a simple example Arches Application to illustrate how to develop and deploy custom applications. The example application called **Arches Dashboard** displays a summary count of resource instances and tiles in a given Arches project. -The **Arches Dashboard** app provides an example of how to build a custom Arches application. Experience with Django in general, and `Django app development `_ in particular, would be very useful for Arches app development. The official Django documentation provides a great starting `tutorial for learning how to create apps `_. +The **Arches Dashboard** app provides an example of how to build a custom Arches application. Experience with Arches in general, and Arches project development in particular, would be very useful for Arches Application development. -Installing the **Arches Dashboard** App ---------------------------------------- +Installing the **Arches Dashboard** Applications +------------------------------------------------ You can add the dashboard to an Arches project in just a few easy steps. 1. Install it from this repo (or clone this repo and pip install it locally): diff --git a/docs/developing/getting-started/customization-considerations.rst b/docs/developing/getting-started/customization-considerations.rst index c96100d..135d3e6 100644 --- a/docs/developing/getting-started/customization-considerations.rst +++ b/docs/developing/getting-started/customization-considerations.rst @@ -7,8 +7,9 @@ If you are leading a project or organization considering customizing Arches soft The practices described here will reduce costs, reduce long term maintenance and security risks, and will lead to greater impact, enhanced sustainability, and open doors for future opportunities. That said, to maximize sustainability, security, maintainability, quality and impact, it is best practice to coordinate and discuss customization plans with the wider Arches open source community. If you haven't already done so, please join the `Arches Community Forum `_! -More Sustainable Pathways toward Customization -============================================== + +Custom Extensions +================================== To increase the likelihood that customizations will have long term compatibility and maintainability with Arches, please use the customization patterns supported and documented by Arches. These patterns include: @@ -27,12 +28,11 @@ To increase the likelihood that customizations will have long term compatibility Adherence to the extension design patterns helps to isolate your customizations from changes to the core of Arches. Following Arches extensions design patterns will also increase the likelihood that there will be relevant documentation and community help if the extensions need updates in the future. Certain customizations are easier to maintain over time. For example, an overwritten HTML template is generally simpler to upgrade than an inherited Arches Python class or an overwritten Django view. You should factor such considerations into long term resource planning. -Customizations Beyond Extensions -================================ -While the Arches extensions architecture offers a great deal of flexibility, there may be scenarios where you need additional flexibility. From a sustainability and maintenance perspective, this scenario has important risks that need to be understood and factored into long term resource planning and engineering. - -Managing long term sustainability and maintenance risks should be a core software engineering focus. As much as possible, you should ideally isolate your customized module as much as possible from the core of Arches. One way preferred way to accomplish this is to develop **Arches Apps** (see: :ref:`Creating Applications`), which are discrete Python packages that can be integrated into one or more Arches projects. The **Arches Apps** documentation details their sustainability advantages. +Arches Applications +=================== +While the Arches extensions (see above) architecture offers a great deal of flexibility, there may be scenarios where you need additional flexibility. From a sustainability and maintenance perspective, ideally you should isolate your customized module as much as possible from the core of Arches. One way to accomplish this is to develop an **Arches Application** (see: :ref:`Creating Applications`), which are discrete Python packages that can be integrated into one or more Arches projects. The **Arches Applications** documentation details their development as well as their sustainability advantages. +Arches Applications are a powerful way to create customizations that are isolated from the core of Arches. This isolation can help to reduce the risk of future maintenance and upgrade challenges. Arches Applications create reusable components that can be developed and maintained independently of the core Arches software, and can be shared with the wider Arches community. This can help to ensure that your customizations are more maintainable over time and can help to reduce the overall cost of development and maintenance. API Based Customizations ========================