Proposed Feature Development PR process

[Ezward]

Recently we had a lively discussion on Donkey Car quality issues. It was suggested that users in the San Diego group were driven away because version 4.x had bugs and broken features or used features were dropped. I myself when looking at the code see a lot of dead code and unused features that make maintenance a chore. I'm proposing a more formal Feature Development and Acceptance process in order to:

• Improve quality by requiring testing prior to merging
• Improve stability by reducing unintended breakage and formalizing deprecation
• Improve usability by requiring documentation updates
• Improve maintainability by reducing code dumping

This is for discussion. Please add your comments to this issue.

Proposed Feature Development Pull Request Process for discussion

• A feature branch to be merged must have an Issue so we can track it.

  • The issue must include links to the code branch AND the documentation branch.
  • The issue must include context for the feature
    • the goals of the feature
    • how the feature should work.
    • how the feature does NOT work (to avoid spurious bug reports)

• The issue should include how it might affect existing features and/or code.

• The issue should include a manual test plan that includes the happy path and tests for any potentially affected features.

  • Ideally the actual 'test' IS the documentation branch as instructions on how to use the feature. In other words, we hope the documentation is so good we can simply test against it. If there are no changes to how a feature works or should be tested, then the Issue can just point to the current documentation.
  • The test plan must include hardware configurations and the associated myconfig settings to be tested.
  • If the test plan is extensive it can be moved it's own issue and linked in the main issue.

• The pull request must include unit tests for the new feature.

• The pull request must pass our linting tests and must match our coding standards, particularly for code documentation (commenting) (standards TBD).

• The pull request cannot be merged until there is a test plan and it has been executed and it passes on the high priority hardware configurations (those are TBD).

• The pull request cannot be merged until the document branch is updated to be consistent with the changes in the feature.
  If the feature is to replace an existing feature then it should strive to be additive, leaving the old feature intact but marked using the @deprecated decorator so user's current setups are not immediately broken, but they are on notices that the old feature is to be removed in a future release.

TODO:

• agree on and implement linting rules
• agree on and document coding standards (beyond linting)
• agree on high priority hardware configurations for testing. Map these to users that have the configurations and would be willing to test.
• create a Feature Issue template that includes the required sections and documents how to use them.

[Ezward]

See this issue and related PRs for an example:
Issue #945
Code PR #951
Docs PR autorope/donkeydocs#25