The purpose of this page is to outline our process for working with publishers that have developer access on Newspack. Publishers with developer access receive development support, staging sites, early access to alpha releases, and a GitHub repository with all the tooling needed to develop and deploy code following WordPress and Newspack best practices.

We want to empower and support your custom development efforts and ability to extend the Newspack platform. At the same time, nobody wants unexpected site downtime, performance degradation, or security issues.

Communication is the top priority to keep us working well together. Both Newspack and publishers’ development teams need visibility into what each other is working on, what’s on the roadmap, and what has been deployed recently.

Communication pathways

  • For discussing custom development projects, your primary Slack is the preferred tool, not email or video. This ensures everyone can catch up on previous discussions and has access to any discussion between our teams. Using Slack also makes it simpler to share code snippets or links to reference documentation.
  • Communicate any upcoming deadlines or large releases to the Newspack team in Slack, so we can monitor the site and ensure things are working properly or help roll back a deploy if needed.
  • The Newspack Help Channel is the place to request training on new features, get general advice, or report issues with Newspack features. It is not the place to get advice or troubleshooting for anything related to custom development, as it is unlikely they will be able to help much. For custom-development-related issues, your primary Slack channel is the best place to get assistance.
  • You should keep a changelog of new features or changes that you make, and pin it to the top of your primary channel. This will help the Newspack team troubleshoot custom-development-related issues.

New Publisher Onboarding

If you are a publisher onboarding to Newspack with developer access, or if you are already on Newspack and are wanting to get set up for developer access, a Newspack engineer will hold an initial call with your team to onboard you to our custom development program, answer any questions you may have, and talk through your custom development needs and plans.

We’ll also help you set up your custom development GitHub repository where all your code will live. Newspack provides a standardized code repository and workflow that streamlines the development and deployment process while maintaining coding standards. Any code developed on top of the Newspack platform is truly your code — you will own the repository and code and can keep it if you ever do leave Newspack.

What’s included in developer access

Our development support is designed to help you succeed with custom development on the Newspack platform, while maintaining clear boundaries around what we can provide:

What we do provide:

  • WordPress and Newspack development guidance: Early consultation when planning new projects. We can help you understand requirements, suggest approaches, and share insights on best paths forward using WordPress and Newspack features.
  • Code review: Review of your code from the perspective of WordPress and Newspack development best practices, coding standards, performance considerations, and security. Note that code reviews are static analysis only—we do not run or test your code.
  • Platform expertise: Advice on how to work with Newspack features, extend functionality, and integrate with our platform architecture.
  • Troubleshooting assistance: Help diagnosing issues that may involve interactions between custom code and Newspack core functionality.

What we don’t provide:

  • Unlimited consultation time: While we’re here to help, we ask that you come prepared with specific questions and have done initial investigation on your own.
  • Writing custom code: We don’t write custom code for your specific features or requirements. Your development team is responsible for implementing any custom code.
  • Quality assurance testing: We don’t test your custom features, run your code, or perform QA on custom functionality.
  • Ongoing maintenance: We don’t maintain, update, or fix bugs in your custom code over time.
  • Training on general web development: We provide Newspack and WordPress-specific guidance, not general programming or web development training.

Guidelines for development

When planning a new project: When working on requirements for a new project you should run the idea by your primary TAM early in the process. This will let us provide guidance around approaches or existing solutions. Early heads-up on platform innovation and custom plugin creation is more necessary than an early heads-up on content presentation changes.

Staging environments: Newspack can provide up to 2 staging environments, which are clones of your site for development and testing purposes. New features should be tested within a staging environment before being deployed to the live environment. The Newspack development tooling makes it simple to deploy changes to staging environments by merging code to a git branch.

Code practices: Code should follow the WordPress VIP Coding Standards and the WordPress Coding Standards. This will catch the majority of common performance and security issues and ensure that the code is readable and following best-practices. The Newspack custom development tooling will automatically run these checks on all code changes.

Workflow for deployments: The Newspack custom development tooling will automatically deploy code to a live or staging site when it is merged into the corresponding git branch. Ideally deploy custom code only Monday through Thursday during core support hours in case urgent troubleshooting from the Newspack team is required.

Documentation: It’s very important that you keep a document of all the custom code that’s running on your site, what they are, and why you need it. The custom code repository will help you organize the code in such a way that each independent feature has its own place. This greatly helps when we need to debug things together.

Changelog: To maintain visibility into recent changes to the site, you should maintain an internal changelog spreadsheet of all changes released to the site, in reverse chronological order, which can be accessed by your team and the Newspack team at any time. This document should be pinned to the main private channel in Newspack Slack.

Feature requests and contributions back to Newspack

We believe that this is a partnership relationship, and we’re always willing to receive feedback, bug reports, feature requests, and contributions.

In some cases, we are able to incorporate some of your needs and feature requests if they will serve the broader Newspack community. These are the general rules of thumb we use:

  • This is a great idea with a high impact and will serve other publishers as well. Newspack will build this into the core software for everyone.
  • This is a good idea and is within the scope of our product, but has a low priority or low impact, and it’s unlikely that we’ll be able to address it in the short term. We can give you direction around submitting it as a contribution to Newspack, and we’ll review it and incorporate it in our product
  • This is outside the scope of our product or only relevant for a very small number of sites. We can give you directions on the best ways to build it as part of your custom plugin.

When things go wrong

How do we work together when things break? As mentioned above, we recommend not using the Help channel for custom-development-related issues, as it is unlikely they will be able to help much. Instead, vet the issue internally and raise a flag if needed to the Newspack team using @newspack-team in your main private channel in the Newspack Slack. 

When raising an issue, articulate everything done so far to investigate, any changes recently made, and possibly roll back any recent custom code deployments. Overcommunicate. Who is checking what? Who is doing what next? What have we already looked at? The Newspack team is responsive and will investigate urgently, and the more information you can provide the sooner we can get a resolution.