From 3daf75c28d89acc98854aab797f7e8997169d6ff Mon Sep 17 00:00:00 2001 From: Steve Wirt Date: Thu, 17 Oct 2024 15:09:04 -0400 Subject: [PATCH 01/11] 1450-Add Contrig First documentation. --- common-practices-tools/README.md | 2 ++ .../contribution/contrib-first.md | 24 +++++++++++++++++++ 2 files changed, 26 insertions(+) create mode 100644 common-practices-tools/contribution/contrib-first.md diff --git a/common-practices-tools/README.md b/common-practices-tools/README.md index 22f1550394..caa3cd121c 100644 --- a/common-practices-tools/README.md +++ b/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 stewards of OpenSource we practice a Contribute First 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 diff --git a/common-practices-tools/contribution/contrib-first.md b/common-practices-tools/contribution/contrib-first.md new file mode 100644 index 0000000000..537f53d553 --- /dev/null +++ b/common-practices-tools/contribution/contrib-first.md @@ -0,0 +1,24 @@ +# Contrib First + +Whenever we are building something that could be of use to more than just one project or client, we build it as contributed work first. + +## 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. 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) +- **Reusablity** - CivcActions other clients can benefit from work that was already done. +- **Security** - contributing our work to an open source project like Drupal means it it receives security coverage by the Drupal security team and the public. +- **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 be 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 issue are public. The commits are public. Everyone can contribute. + +## Examples of modules 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) +- [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) +- [Post API](https://www.drupal.org/project/post_api) +- [Vertex AI Search](https://www.drupal.org/project/vertex_ai_search) From 5560bc0290f7e6c749424e402e0c1ec77ae814b3 Mon Sep 17 00:00:00 2001 From: Steve Wirt Date: Thu, 17 Oct 2024 15:12:20 -0400 Subject: [PATCH 02/11] Add link. --- common-practices-tools/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common-practices-tools/README.md b/common-practices-tools/README.md index caa3cd121c..120182547d 100644 --- a/common-practices-tools/README.md +++ b/common-practices-tools/README.md @@ -6,7 +6,7 @@ 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 stewards of OpenSource we practice a Contribute First approach. +As good stewards of OpenSource 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). From f2e462e83d508ac909a6afd7270cd2b8f449afd4 Mon Sep 17 00:00:00 2001 From: Steve Wirt Date: Thu, 17 Oct 2024 15:21:29 -0400 Subject: [PATCH 03/11] Add mkdocs menu item. --- .config/mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.config/mkdocs.yml b/.config/mkdocs.yml index ae6135eb13..7c3af7c864 100644 --- a/.config/mkdocs.yml +++ b/.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 From 95fac68c90a90670b21e0a256fc5bcb213b6cdec Mon Sep 17 00:00:00 2001 From: Steve Wirt Date: Thu, 17 Oct 2024 17:28:54 -0400 Subject: [PATCH 04/11] Apply suggestions from code review --- common-practices-tools/contribution/contrib-first.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/common-practices-tools/contribution/contrib-first.md b/common-practices-tools/contribution/contrib-first.md index 537f53d553..ff54df6532 100644 --- a/common-practices-tools/contribution/contrib-first.md +++ b/common-practices-tools/contribution/contrib-first.md @@ -1,12 +1,12 @@ # Contrib First -Whenever we are building something that could be of use to more than just one project or client, we build it as contributed work first. +Whenever we are building something that could be of use to more than one project or client, we build it as contributed work first. ## 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. 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) - **Reusablity** - CivcActions other clients can benefit from work that was already done. -- **Security** - contributing our work to an open source project like Drupal means it it receives security coverage by the Drupal security team and the public. +- **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. - **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 be 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 issue are public. The commits are public. Everyone can contribute. @@ -22,3 +22,5 @@ Whenever we are building something that could be of use to more than just one pr - [Node Link Report](https://www.drupal.org/project/node_link_report) - [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). From 291313d420d556a79f59b2c5d86ef22d73aa8c07 Mon Sep 17 00:00:00 2001 From: Steve Wirt Date: Thu, 17 Oct 2024 17:58:19 -0400 Subject: [PATCH 05/11] Add module and patch contributions --- .../contribution/contrib-first.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/common-practices-tools/contribution/contrib-first.md b/common-practices-tools/contribution/contrib-first.md index ff54df6532..85ca74625b 100644 --- a/common-practices-tools/contribution/contrib-first.md +++ b/common-practices-tools/contribution/contrib-first.md @@ -10,6 +10,26 @@ Whenever we are building something that could be of use to more than one project - **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 be 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 issue are public. The commits are public. Everyone can contribute. +## Contrib first patches + +In the case of changes needed to existing modules or Drupal core: + +1. We contribute patches to existing issues or create new issues. +2. We use the compose-patches to apply local copies of the contributed patches. + +## Contrib first modules + +When a new module is needed, the process looks like this: + +1. Gather requirements and identify MVP vs nice-to-haves +2. Search for existing modules that might solve the problem. (It might be easier to stretch an existing module than build a new one) +3. Choose a meaningful search engine friendly module name. (crowd sourcing name suggestions is recommended) +4. Create the Drupal project on Drupal.org +5. Populate the project page with a descrion of what is coming. List supporters as CivicActions and the client. If the client does not have a drupal.org page, encourage them to create one. +6. Populate the issue queue on the Drupal project with "Feature requests". Mark any that are part of the MVP as "major". Create issues for any immprovement ideas that pop up. They don't all have to be acted on, but they help shape the road map for where you want the module to go. +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 security coverage. + ## Examples of modules CivicActions built as contrib first - [Allow Only One](https://www.drupal.org/project/allow_only_one) From 8800f13bfe447f77ccc88977cb3c12bf5bc27c8d Mon Sep 17 00:00:00 2001 From: Steve Wirt Date: Mon, 21 Oct 2024 12:21:37 -0400 Subject: [PATCH 06/11] Add link to practice area directions. --- common-practices-tools/contribution/contrib-first.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common-practices-tools/contribution/contrib-first.md b/common-practices-tools/contribution/contrib-first.md index 85ca74625b..ee2c223e56 100644 --- a/common-practices-tools/contribution/contrib-first.md +++ b/common-practices-tools/contribution/contrib-first.md @@ -25,7 +25,7 @@ When a new module is needed, the process looks like this: 2. Search for existing modules that might solve the problem. (It might be easier to stretch an existing module than build a new one) 3. Choose a meaningful search engine friendly module name. (crowd sourcing name suggestions is recommended) 4. Create the Drupal project on Drupal.org -5. Populate the project page with a descrion of what is coming. List supporters as CivicActions and the client. If the client does not have a drupal.org page, encourage them to create one. +5. Populate the project page with a descrion of what is coming. List supporters as CivicActions and the client [directions](../../practice-areas/engineering/drupal/README.md#contribution-to-drupalorg-modules-and-themes). If the client does not have a drupal.org page, encourage them to create one. 6. Populate the issue queue on the Drupal project with "Feature requests". Mark any that are part of the MVP as "major". Create issues for any immprovement ideas that pop up. They don't all have to be acted on, but they help shape the road map for where you want the module to go. 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 security coverage. From fbbcfa98c59beb2bc46e1054d567aa267c371f8b Mon Sep 17 00:00:00 2001 From: Steve Wirt Date: Mon, 21 Oct 2024 15:32:08 -0400 Subject: [PATCH 07/11] Add link to composer-patches plugin. --- common-practices-tools/contribution/contrib-first.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common-practices-tools/contribution/contrib-first.md b/common-practices-tools/contribution/contrib-first.md index ee2c223e56..db036592cb 100644 --- a/common-practices-tools/contribution/contrib-first.md +++ b/common-practices-tools/contribution/contrib-first.md @@ -15,7 +15,7 @@ Whenever we are building something that could be of use to more than one project In the case of changes needed to existing modules or Drupal core: 1. We contribute patches to existing issues or create new issues. -2. We use the compose-patches to apply local copies of the contributed patches. +2. We use the [composer-patches](https://github.com/cweagans/composer-patches) to apply local copies of the contributed patches. ## Contrib first modules From bad11cb302e4aa3c9845e1b81c6e9b9ab73d0364 Mon Sep 17 00:00:00 2001 From: Steve Wirt Date: Tue, 22 Oct 2024 11:49:03 -0400 Subject: [PATCH 08/11] Break content out into engineering specific places. --- .config/mkdocs.yml | 1 + common-practices-tools/README.md | 2 +- .../contribution/contrib-first.md | 35 +++++-------------- ...drupal-contrib-first-module-development.md | 15 ++++++++ ...for-getting-the-most-out-of-open-source.md | 9 ++--- 5 files changed, 31 insertions(+), 31 deletions(-) create mode 100644 practice-areas/engineering/drupal/drupal-contrib-first-module-development.md diff --git a/.config/mkdocs.yml b/.config/mkdocs.yml index 7c3af7c864..d696b7706f 100644 --- a/.config/mkdocs.yml +++ b/.config/mkdocs.yml @@ -122,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 diff --git a/common-practices-tools/README.md b/common-practices-tools/README.md index 120182547d..bea16517b4 100644 --- a/common-practices-tools/README.md +++ b/common-practices-tools/README.md @@ -6,7 +6,7 @@ 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 stewards of OpenSource we practice a [Contribute First](contribution/contrib-first.md) approach. +As good stewards 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). diff --git a/common-practices-tools/contribution/contrib-first.md b/common-practices-tools/contribution/contrib-first.md index db036592cb..4c215c5f40 100644 --- a/common-practices-tools/contribution/contrib-first.md +++ b/common-practices-tools/contribution/contrib-first.md @@ -1,36 +1,19 @@ # Contrib First -Whenever we are building something that could be of use to more than one project or client, we build it as contributed work 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. 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) -- **Reusablity** - CivcActions other clients can benefit from work that was already done. +- **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** - CivcActions other clients 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. -- **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 be 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 issue are public. The commits are public. Everyone can contribute. +- **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** - When we release FOSS, CivicAction, our developers and our clients get positive representation as technology leaders and contributors. -## Contrib first patches - -In the case of changes needed to existing modules or Drupal core: - -1. We contribute patches to existing issues or create new issues. -2. We use the [composer-patches](https://github.com/cweagans/composer-patches) to apply local copies of the contributed patches. - -## Contrib first modules - -When a new module is needed, the process looks like this: - -1. Gather requirements and identify MVP vs nice-to-haves -2. Search for existing modules that might solve the problem. (It might be easier to stretch an existing module than build a new one) -3. Choose a meaningful search engine friendly module name. (crowd sourcing name suggestions is recommended) -4. Create the Drupal project on Drupal.org -5. Populate the project page with a descrion of what is coming. List supporters as CivicActions and the client [directions](../../practice-areas/engineering/drupal/README.md#contribution-to-drupalorg-modules-and-themes). If the client does not have a drupal.org page, encourage them to create one. -6. Populate the issue queue on the Drupal project with "Feature requests". Mark any that are part of the MVP as "major". Create issues for any immprovement ideas that pop up. They don't all have to be acted on, but they help shape the road map for where you want the module to go. -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 security coverage. - -## Examples of modules CivicActions built as contrib first +## Examples of modules 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) diff --git a/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md b/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md new file mode 100644 index 0000000000..00a7274b4e --- /dev/null +++ b/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md @@ -0,0 +1,15 @@ +## Drupal Contrib First module developement + +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: + - 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. +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 pop up. 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 security coverage. diff --git a/practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md b/practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md index 362707ebac..f823a79908 100644 --- a/practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md +++ b/practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md @@ -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,6 +34,7 @@ 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 @@ -60,7 +61,7 @@ Getting patches accepted and applied takes a lot of time and effort. But it's ti - **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. - 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. @@ -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. From 7f0532dd70f1b5b64e52ba7483762ef6090e1d53 Mon Sep 17 00:00:00 2001 From: Steve Wirt Date: Tue, 22 Oct 2024 15:06:25 -0400 Subject: [PATCH 09/11] Adding non Drupal examples and clearer language. --- .../contribution/contrib-first.md | 14 +++++++++++--- .../drupal-contrib-first-module-development.md | 9 +++++++-- ...tips-for-getting-the-most-out-of-open-source.md | 2 +- 3 files changed, 19 insertions(+), 6 deletions(-) diff --git a/common-practices-tools/contribution/contrib-first.md b/common-practices-tools/contribution/contrib-first.md index 4c215c5f40..25facd4e25 100644 --- a/common-practices-tools/contribution/contrib-first.md +++ b/common-practices-tools/contribution/contrib-first.md @@ -1,3 +1,7 @@ +--- +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. @@ -5,24 +9,28 @@ Whenever we are building something that could be of use by more than one project ## 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** - CivcActions other clients 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. +- **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** - When we release FOSS, CivicAction, our developers and our clients get positive representation as technology leaders and contributors. -## Examples of modules CivicActions built as Contrib First +## 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) diff --git a/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md b/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md index 00a7274b4e..6e976bfc01 100644 --- a/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md +++ b/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md @@ -1,4 +1,8 @@ -## Drupal Contrib First module developement +--- +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: @@ -6,10 +10,11 @@ When a new module is needed we try to follow [Contrib First](../../../common-pra 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: + - 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. 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 pop up. 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 security coverage. +8. After the official release, opt in to [Drupal security coverage](https://www.drupal.org/drupal-security-team/security-advisory-process-and-permissions-policy). diff --git a/practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md b/practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md index f823a79908..817b095077 100644 --- a/practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md +++ b/practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md @@ -34,7 +34,7 @@ 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. +- 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 From 4920877c861ff57c0307e0fd17d8aebfb9dfe08b Mon Sep 17 00:00:00 2001 From: Steve Wirt Date: Tue, 22 Oct 2024 15:14:18 -0400 Subject: [PATCH 10/11] Fix duplicate heading. --- common-practices-tools/README.md | 2 +- common-practices-tools/contribution/contrib-first.md | 8 ++++---- .../drupal/drupal-contrib-first-module-development.md | 7 ++++--- ...eloper-tips-for-getting-the-most-out-of-open-source.md | 8 ++++---- 4 files changed, 13 insertions(+), 12 deletions(-) diff --git a/common-practices-tools/README.md b/common-practices-tools/README.md index bea16517b4..cb36f9f70c 100644 --- a/common-practices-tools/README.md +++ b/common-practices-tools/README.md @@ -6,7 +6,7 @@ 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 stewards of Free and Open Source Software (FOSS) we practice a [Contribute First](contribution/contrib-first.md) approach. +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). diff --git a/common-practices-tools/contribution/contrib-first.md b/common-practices-tools/contribution/contrib-first.md index 25facd4e25..c3414682d0 100644 --- a/common-practices-tools/contribution/contrib-first.md +++ b/common-practices-tools/contribution/contrib-first.md @@ -9,13 +9,13 @@ Whenever we are building something that could be of use by more than one project ## 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. +- **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** - When we release FOSS, CivicAction, our developers and our clients get positive representation as technology leaders and contributors. +- **Visibility** - CivicActions, our developers and clients earn positive representation as technology leaders and contributors. ## Examples of FOSS CivicActions built as Contrib First @@ -24,7 +24,7 @@ Whenever we are building something that could be of use by more than one project - [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) + - [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) diff --git a/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md b/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md index 6e976bfc01..f3296276a7 100644 --- a/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md +++ b/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md @@ -2,7 +2,7 @@ title: Drupal Contrib First module development --- -## 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: @@ -10,11 +10,12 @@ When a new module is needed we try to follow [Contrib First](../../../common-pra 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: - + - 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. -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 pop up. They don't all have to be acted on, but they help shape the road map for where you want the module to go. + +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). diff --git a/practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md b/practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md index 817b095077..3baf83b13e 100644 --- a/practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md +++ b/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 @@ -42,7 +42,7 @@ Changes we might make to existing modules fall into three general categories, wh - **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: @@ -58,7 +58,7 @@ 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 [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. @@ -68,7 +68,7 @@ Getting patches accepted and applied takes a lot of time and effort. But it's ti ## 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. From fbadc1b58895518c8110a62ea4a59441bb0e0dd5 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 25 Oct 2024 20:30:27 +0000 Subject: [PATCH 11/11] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- ...drupal-contrib-first-module-development.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md b/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md index f3296276a7..5dcf873a24 100644 --- a/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md +++ b/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md @@ -6,16 +6,16 @@ title: 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: - - - 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. - -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). +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: + + - 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. + +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).