PushType development contribution guidelines


(Aaron Russell) #1

How to contribute to PushCode

Firstly, thank you! It’s great that you’re interested in contributing. PushType is 100% free and open source, and we’re working hard to establish an active and healthy community of individuals contributing to it’s development.

The following is a set of guidelines for contributing to PushType. Don’t worry, there are no hard and fast rules, but please do take a moment to read through these guidelines so you know where to start and how we roll.

Code of conduct

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code.

Reporting issues

The Github issue list is exclusively for reporting bugs and tracking planned features and enhancements. For beginner questions, support, or to suggest and discuss new features, please use the official PushType community discussion site.

  • Try searching first to see if the same problem has already been reported. If it has, add a comment to the existing issue instead of opening a new one.
  • Provide a clear and descriptive title for the issue to help identify the problem.
  • Describe the exact steps necessary to reproduce the problem.
  • Explain the behaviour you expected to see following the steps, and describe the behaviour you observed instead and why this is a problem.
  • Copy and paste any errors from the application log or the web browser console in to the issue report.
  • Please format any errors or code snippets using Markdown code blocks.
  • Include relevant details about your configuration and environment such as Ruby, Rails and PushType versions, and if necessary your browser and operating system.

Suggesting improvements

Please do not open an issue on GitHub to suggest new features and improvements to PushType. Instead, share your ideas in the PushType community feature category and engage with the other developers and users.

Try searching first to check your idea hasn’t already been discussed. Also, check the PushType roadmap in case it’s already in the pipeline.

Keep in mind that not every feature is destined to be in PushType. So, before jumping in and writing code, discuss your idea with the community, establish a desire for the development and a broad consensus for how it should be approached.

For accepted and planned features, GitHub issues will be created to track the work. Larger more complex developments may be broken down in to smaller issues and organised in a GitHub project.

Finding something to work on

So, you’re ready to start contributing to PushType but unsure where to begin? You can start by filtering through the Github issue list.

  • Beginner issues - issues that should be relatively simple to address in a few lines of code.
  • Help wanted issues - more involved issues, often where specific expertise is needed.

If you feel there’s something you can help out with, let someone know by posting a comment and explaining how you intend to resolve the issue. Once the issue has been assigned to you, it’s all yours :raised_hands:.

Helping with larger features and projects

If you would like to get more involved and help steer the design and development of PushType, then head over to the official PushType community site and introduce yourself.

  • PushType Roadmap - this wiki topic lists features that are either planned for the next releases or on the wishlist.
  • Features category - contribute to these discussions and argue for (or against) proposed features and flesh them out in to workable specs.
  • Dev category - Find out more about working on PushType, configuring development environments, coding conventions and so forth.

Development setup

PushType consists of four separate Rails engines, each of which are published as gems:

  • PushType::Core
  • PushType::Api
  • PushType::Admin
  • PushType::Auth

The Github repo contains the code for all of the above engines. At the root of the project is the gemspec for the main push_type gem. This is a simple wrapper for the four separate gems.

In each of the “admin”, “api”, “auth” and “core” directories is the code and gemspecs for the respective Rails engines.

Installing Ruby and Node dependencies

After cloning the repository, install the gem dependencies for each of the Gemfiles:

> for d in core admin api auth; do cd $d && bundle install && cd ..; done
> bundle install

The “admin” engine uses webpack to build the front end assets. Once the JavaScript dependencies have been installed, a rake task can be used to run webpack.

> cd admin
> npm install
> rake webpack

Running tests

From the project root you can run the entire project test suite. This iterates through each of the gem directories and runs their respective tests.

> rake test

Within any of the four gem directories, there are two test tasks:

  • rake test_app - Removes and regenerates the dummy test app.
  • rake test - Runs the test suite for that gem.

Whilst working on PushType, it can be useful to run the dummy test app server and view it in the browser as you make changes and write new code.

Tests

All new features and improvements require test coverage. The test suite uses the minitest framework and is written in the spec style.

Be pragmatic with testing. Writing tests shouldn’t be a major chore, and not every line of code requires test coverage. But the test suite should offer assurances that the new features and changes work under as many foreseeable circumstances as practical.

Prefer smaller shallow tests over deep (and possibly brittle) tests. The test suite should be fast, easy to reason with, and reliable.

Pull requests

TBC…


Welcome to the PushType community
(Aaron Russell) #4

(Aaron Russell) #5

PushType’s contribution guidelines have had a complete rewrite. Bumping this topic. :point_up: