1450-Add Contrib First documentation. (#1451)

* 1450-Add Contrig First documentation.

* Add link.

* Add mkdocs menu item.

* Apply suggestions from code review

* Add module and patch contributions

* Add link to practice area directions.

* Add link to composer-patches plugin.

* Break content out into engineering specific places.

* Adding non Drupal examples and clearer language.

* Fix duplicate heading.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: Steve Wirt <Steve Wirt>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.config/mkdocs.yml

@@ -73,6 +73,7 @@ nav:
           - common-practices-tools/agile/sprint-retrospectives.md
       - common-practices-tools/balance-scores.md
       - common-practices-tools/best-practices-for-managers-and-team-members.md
+      - common-practices-tools/contribution/contrib-first.md
       - CivicActions style guide: "https://civicactions-style-guide.readthedocs.io/en/latest/introduction/brand-overview/"
       - Security awareness and tools:
           - common-practices-tools/security/README.md
@@ -121,6 +122,7 @@ nav:
               - practice-areas/engineering/drupal/drupal-for-drupal-engineers.md
               - practice-areas/engineering/drupal/drupal-glossary.md
               - practice-areas/engineering/drupal/most-important-decision-in-developing-a-drupal-site-contributed-vs-custom-development.md
+              - practice-areas/engineering/drupal/drupal-contrib-first-module-development.md
               - practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md
           - practice-areas/engineering/git.md
           - practice-areas/engineering/security-compliance.md

common-practices-tools/README.md

@@ -6,6 +6,8 @@ title: Common practices and tools
 
 As part of our [CivicActions culture](../about-civicactions/culture.md), we share a set of practices and tools to be effective communicators, team members [working in Agile](agile/README.md), and managers of client work and company administration.
 
+As good caretakers of Free and Open Source Software (FOSS) we practice a [Contribute First](contribution/contrib-first.md) approach.
+
 Underpinning our chosen technology stack is a [required security awareness process](security/README.md) that gets everyone set up to work online safely and avoid the scourge of [phishing](security/README.md#phishing-and-social-engineering).
 
 ## Get support

common-practices-tools/contribution/contrib-first.md

@@ -0,0 +1,37 @@
+---
+title: Contrib First
+---
+
+# Contrib First
+
+Whenever we are building something that could be of use by more than one project or client, we build it as contributed work first, if our contract and security concerns allow for it. Contrib First is an approach we take with both patches to FOSS software and new contributions.
+
+## Rationale for contrib first
+
+-   **Fiscal responsibility** - Building it and contributing it means that other government agencies will never have to pay to build the same thing twice. This helps agencies comply with Federal Source Code Policy: Achieving Efficiency, Transparency, and Innovation through Reusable and Open Source Software [OMB Memorandum M-16-21](https://obamawhitehouse.archives.gov/sites/default/files/omb/memoranda/2016/m_16_21.pdf)
+-   **Reusability** - CivicActions other clients and the public at large can benefit from work that was already done.
+-   **Security** - contributing our work to an open source project like Drupal means it may receive security coverage by the Drupal security team and the public. It is made more secure by getting more eyes on the code and more users surfacing any issues.
+-   **Avoiding the gift that never happens** - Clients are not typically supportive of taking working local software that was already built for them and in use by them, and then paying to move or refactor that software to become open source. The benefit is too small for the cost. By building it as contributed code first, there is no extra cost.
+-   **Development happens in the open** - The issues are public. The commits are public. Everyone can contribute improvements.
+-   **Reliability** - A solution built for contribution is often better designed, and better documented than a local solution meant to "just get it done". By putting our company and personal names on it publicly we commit to a quality product. Releasing a FOSS solution also increases the number of testers and edge cases that can surface and reduce bugs in the code.
+-   **Scalability** - Contributed FOSS is more scalable than one-off solutions and can grow with the power of the FOSS community.
+-   **Visibility** - CivicActions, our developers and clients earn positive representation as technology leaders and contributors.
+
+## Examples of FOSS CivicActions built as Contrib First
+
+-   [Allow Only One](https://www.drupal.org/project/allow_only_one)
+-   [Codit: Batch Operations](https://www.drupal.org/project/codit_batch_operations)
+-   [Codit: Menu Tools](https://www.drupal.org/project/codit_menu_tools)
+-   [Content Model & Site Documentation](https://www.drupal.org/project/content_model_documentation)
+-   [Drupal Knowledge Archive Network (DKAN Open Data Portal)](https://github.com/GetDKAN/dkan)
+    -   [CMSDS Open Data Components](https://github.com/GetDKAN/cmsds-open-data-components)
+-   [Drydock Cloud](https://github.com/drydockcloud)
+-   [Entity Field Fetch field](https://www.drupal.org/project/entity_field_fetch)
+-   [GovDelivery Bulletins](https://www.drupal.org/project/govdelivery_bulletins)
+-   [Mermaid Diagram Field](https://www.drupal.org/project/mermaid_diagram_field)
+-   [Node Link Report](https://www.drupal.org/project/node_link_report)
+-   [Open Accessibility Conformance Report](https://github.com/GSA/openacr)
+-   [Post API](https://www.drupal.org/project/post_api)
+-   [Vertex AI Search](https://www.drupal.org/project/vertex_ai_search)
+
+See more of [CivicActions Drupal contributions](https://drupal.org/civicactions).

practice-areas/engineering/drupal/drupal-contrib-first-module-development.md

@@ -0,0 +1,21 @@
+---
+title: Drupal Contrib First module development
+---
+
+# Drupal Contrib First module development
+
+When a new module is needed we try to follow [Contrib First](../../../common-practices-tools/contribution/contrib-first.md), the process looks like this:
+
+1.  Check with project leadership to make sure the contract allows for it.
+2.  Gather requirements and identify MVP vs nice-to-haves
+3.  Search for existing modules that might solve the problem. (It might be easier to stretch an existing module than build a new one)
+4.  If opting to build a new module:
+    <!--lint disable list-item-content-indent code-block-style -->
+        - Choose a meaningful search engine friendly module name. (crowd sourcing name suggestions is recommended)
+        - Create the Drupal project on Drupal.org
+        - Populate the project page with a description of what is coming. List supporters as CivicActions and the client [directions](./README.md#contribution-to-drupalorg-modules-and-themes). If the client does not have a drupal.org page, get help from your PM to encourage them to create one.
+    <!--lint enable list-item-content-indent code-block-style -->
+5.  Populate the issue queue on the Drupal project with "Feature requests". Keep them as atomic as possible. Mark any that are part of the MVP as "major". Create issues for any improvement ideas that emerge. They don't all have to be acted on, but they help shape the road map for where you want the module to go.
+6.  Close the issues as you go and be sure to credit yourself, CivicActions, and the client.
+7.  Begin with alpha releases. Ideally when all your MVP/major issues are closed, you are ready for the official release.
+8.  After the official release, opt in to [Drupal security coverage](https://www.drupal.org/drupal-security-team/security-advisory-process-and-permissions-policy).

practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md

@@ -6,7 +6,7 @@ title: Drupal developer tips to get the most out of open source
 
 Note: _This was originally a blog post on the CivicActions site authored by [Nedjo Rogers](https://nedjo.ca/) ([d.o](https://www.drupal.org/u/nedjo)) on November 19, 2008._
 
-I [recently suggested](../drupal/most-important-decision-in-developing-a-drupal-site-contributed-vs-custom-development.md) that the way we approach new development is the most important factor in determining the long term value of our work. But just how can developers using Drupal make the most of open source by ensuring that participating and contributing is an essential part of our daily workflow? Here are some practical tips that come out of our experience at CivicActions and that can guide you in deciding how to approach new development to get the full benefit of open source. Read on as well for a discussion of patching vs. hacking vs. forking and of how to get attention for your patches.
+I [recently suggested](../drupal/most-important-decision-in-developing-a-drupal-site-contributed-vs-custom-development.md) that the way we approach new development is the most important factor in determining the long term value of our work. But how can developers using Drupal make the most of open source by ensuring that participating and contributing is an essential part of our daily workflow? Here are some practical tips that come out of our experience at CivicActions and that can guide you in deciding how to approach new development to get the full benefit of open source. Read on as well for a discussion of patching vs. hacking vs. forking and of how to get attention for your patches.
 
 ## Approach to new development
 
@@ -18,9 +18,9 @@ Before wading into coding, it's important to take a good hard look at what's out
     -   **Existing module** Is there an existing well-coded module that covers most of the need? If so, use the existing to provide the bulk of the solution.
 
         -   **Existing patch** Search the drupal.org issue queue for issues similar to yours. Does a patch exist that you could use, test, improve, and review? If so, do so.
-        -   **New patch(es)** If not, produce a patch or patches on the module to achieve the changes. Contribute the patch to a new or existing issue with ample explanation.
+        -   **New patch(es)** If not, produce a patch or patches on the module to achieve the changes as [Contrib First](../../../common-practices-tools/contribution/contrib-first.md). Contribute the patch to a new or existing issue with ample explanation.
 
-    -   **New contrib module** If there is no existing module to cover the need, consider a small, focused new module for contributing back on drupal.org.
+    -   **New contrib module** If there is no existing module to cover the need, consider a small, focused new module for contributing back on drupal.org as [Contrib First](../../../common-practices-tools/contribution/contrib-first.md). See [guidance on building a module as Contrib First](./drupal-contrib-first-module-development.md).
     -   **New contrib module set** In cases where the problem is large, avoid producing a large, monolithic module that does a lot of distinct things. Instead, break the work into small distinct modules, not necessarily packaged in the same project. Wherever possible, rely on existing well coded API modules as components of your solution.
 
 -   **Theme modifications** Is it a presentation-type change? Consider implementing at the theme level. However, avoid introducing new logic or functionality at the theme level. The following should be avoided wherever possible at the theme level:
@@ -34,14 +34,15 @@ In summary:
 -   When it's necessary to build anew, focus first on doing so to a high, generic, contributed standard.
 -   Try to produce custom (site-specific closed source) modules only when the needs are limited in scope and truly specific to the site.
 -   Try to save the theme layer for what it's intended for--final presentation, look and feel.
+-   When we work on a FOSS contribution for a client(s), all of the work should be billable to that client. When doing maintenance on a contribution for no particular client, that work should be reccorded as community participation (PRODEV_COMPART -> Community Participation). You will need to ask to be added to your options in Slack #unanet.
 
 ## Patching vs. hacking vs. forking
 
 Changes we might make to existing modules fall into three general categories, which have very distinct implications.
 
 -   **Patches** A patch is a contribution to a project that can reasonably be expected to be accepted. A patch is generic (not specific to a particular site). It's contributed back to the codebase with the confidence that in all likelihood it will be accepted. Thus, a patch is a short-term change--once it is accepted, the codebase will again be clean.
 -   **Hacks** A hack is a small change made to a file or files in the knowledge that it is unlikely to be accepted as a contribution to the original project. A hack may be made e.g. to provide customizations required by a client. Hacks may e.g. cause code conflicts when code is updated to a new version. Hacks have permanent costs--they must be maintained in perpetuity.
--   **Forks** A fork is extensive customizations made to an existing project to the extent that the codebase is now fundamentally customized. A fork basically converts an existing project into a custom module that must be permanently maintained on a custom basis for the site in question. Forking implies major long term costs and largely undermines the benefits of open source development, e.g., minimization of future maintenance and upgrade costs. Forks should be avoided whenever possible.
+-   **Forks** A fork is extensive customizations made to an existing project to the extent that the codebase is now fundamentally customized. A fork converts an existing project into a custom module that must be permanently maintained on a custom basis for the site in question. Forking implies major long term costs and largely undermines the benefits of open source development, e.g., minimization of future maintenance and upgrade costs. Forks should be avoided whenever possible.
 
 In weighing potential changes, it's essential to figure out what kind of change we're making and to carefully weigh costs and benefits, ensuring that the client too is aware of long term implications. At every stage, we should ask:
 
@@ -57,17 +58,17 @@ Getting patches accepted and applied takes a lot of time and effort. But it's ti
 
 -   **Make your changes generic** Avoid site-specific hacks wherever possible. Do this e.g. through adding configuration options.
 -   **Work with the current development branch** Active development on a particular module may have passed on from the Drupal version your site is in. If so, take the time to convert your patch to the active development version. If you can get it applied there, you might be able to backport it. Even if a backport doesn't get applied, you're still doing well. When the site you're working on is upgraded in future, there'll be one less patch to worry about.
--   **Break up patches** When submitting patches, it's essential that you break them up into logically distinct issues. Yes, it's a lot more work. Yes, it's tempting to just roll a single patch for the various changes you might make to a module--new features, bug fixes, etc. But doing so will often sink any chance you have of getting the patch applied. How to do this in practice? Say you maintain an SVN repository of the site you're working on, as many Drupal development shops do.
+-   **Break up patches** When submitting patches, it's essential that you break them up into logically distinct issues. Yes, it's a lot more work. Yes, it's tempting to only roll a single patch for the various changes you might make to a module--new features, bug fixes, etc. But doing so will often sink any chance you have of getting the patch applied. How to do this in practice? Say you maintain an SVN repository of the site you're working on, as many Drupal development shops do.
     -   Maintain (outside of SVN) a clean checkout of the module in question for each issue. In that checkout, make only the changes you need for that issue. Generate a patch.
     -   In your SVN repository checkout, apply each of the patches you've generated. You end up with the cumulative total of the patches, but you're able to keep them distinct.
--   **Communicate outside the patch queue** Connect with others in IRC in [#drupal (we use Slack now)](https://www.drupal.org/slack). Participate in or initiate discussions on [groups.drupal.org](https://groups.drupal.org/). Selectively and respectfully contact other developers via email to ask for feedback.
+-   **Communicate outside the patch queue** Connect with others in [drupal Slack](https://www.drupal.org/slack). Participate in or initiate discussions on [groups.drupal.org](https://groups.drupal.org/). Selectively and respectfully contact other developers via email to ask for feedback.
 -   **Follow up** It's essential that you follow up on the patches you post. Answer questions. Refresh patches.
 -   **Request CVS access** If it looks like the maintainer could use some help, request CVS write access to the project. Wait until you've already contributed some sound patches. Then say, e.g., "I'm going to be working a lot with this module for the next few weeks/months and will be contributing a lot of patches. I'll always work through the issue queue. Could I get CVS access?"
 -   **Co-maintain** If it looks like you'll be working in the longer term on the project, offer to be a co-maintainer of a module. Like requesting CVS write access, this works best if you've started small by proving yourself through e.g. some pure bug fix patches or small commonly needed features.
 
 ## Reaping the benefits
 
-Coding to high standards and contributing back has very tangible benefits, the type that project managers and bookkeepers can easily understand, including:
+Coding to high standards and contributing back has very tangible benefits, the type that project managers and bookkeepers can understand, including:
 
 -   Reduced upgrade and maintenance costs.
 -   Greater stability.
@@ -82,4 +83,4 @@ But there are also a lot of less direct or tangible but equally important reward
 -   _Contacts_ Engaging with the community to work on solving common problems helps connect you with others interested in the same things you are. These contacts can really help in finding new projects to take on.
 -   _Satisfaction_ There's a definite satisfaction that comes from feeling you've not only solved a problem but you've solved it well.
 
-In short: if contributing back is an afterthought at best, we're missing out on most of the benefit of open source.
+In short: if contributing back is an afterthought at best, we're missing out on most of the benefit of open source, please [Contrib First](../../../common-practices-tools/contribution/contrib-first.md) if possible.