Skip to content

Latest commit

 

History

History
68 lines (46 loc) · 6.15 KB

CONTRIBUTING.md

File metadata and controls

68 lines (46 loc) · 6.15 KB
Raw

Contributing

👍🎉 First off, thanks for taking the time to contribute! 🎉👍 Please reach out to ericsteen1@gmail.com if you have any questions.

Welcome to The Automata Project!

We are eager for your contributions and very happy you found yourself here! Here are our current needs:
  • Elixir Alchemists with Design, Architecture, Scalable OTP Best Practices Expertise
  • AI, Cognitive Architecture & Behavior Tree Expertise
  • ETS, Reinforcement Learning, BlackBoard Systems, & Utility AI Expertise
  • Test Coverage
  • Documentation
  • Senior Code Reviewers to ensure Quality
  • Willingness and motivation to learn it all
Where to get started contributing

A good place to start is in the project kanban. Especially those threads labeled 'good first issue', 'testing'.

Please join the slack channel and/or reach out to ericsteen1@gmail.com if interested!

If in doubt, check the wiki. 🕵️

Definitely check out the Goals on the wiki. This is currently the focal point for the project defining short, medium, and long term problem solving goals across project dimensions. New issues should come from solving these problems "in goal form". Regular brain-storming and question-storming should be conducted with the end game in mind.

See How it works for a high level view of the project, and check out the docs.

See Future Directions for more on what's in the works.

Where to ask for help:
  1. The Automata Project Slack Channel
  2. Elixir Forum
  3. Elixir Slack Channel
  4. Stack Overflow
  5. Reddit
  6. Quora

Engineering Standards & Best Practices

Check the #dev or #testing channels on slack for questions/info.

Design Standards

  1. Abstraction & Modularity are key. Spend the time and/or Ask on the Slack Channel to find the right abstraction. In terms of modularity, If its more than 10-20 lines, put it in a unit Function, Module or Struct that is tested and named well (by its role in the context if possible, rather than its data type or random name).
  2. Meta-programming will be heavily used as this is a framework, but it is important to know where it is useful and where its not. It is wise not to overuse clever meta-programming magic. If your not sure, ask, or use the force Luke (if your a Jedi).
  3. Use function pattern matching over for other types of enumeration wherever possible as this is a first-principle in Elixir systems.
  4. If your not sure how to do something, rather than do a hack, put a skeleton in place and submit a PR so a more senior engineer can provide guidance.

Coding Standards

  1. No shortcuts or Rush Jobs. Quality is job #1. We are creating something of very high quality, built to stand the test of time. Strive for 0% technical debt (the best kind of debt). Frameworks are poorly suited to “agile” practices, since they require foresight and a lot of generic capabilities. Today's emphasis on “agile” development is predicated on the developer's ignorance of what is required. Frameworks cannot be developed in that manner, since they are generic and devoid of ultimate functionality. They are all about potential, not actual end-user functionality. If you don't know the best way to do something, ask a core team member, or reach out to the very helpful Elixir community. See the list of resources.
  2. Always think about what can go wrong, what will happen on invalid input, and what might fail, which will help you catch many bugs before they happen.

PR Review Standards

  1. Code Reviews by core team members are required before merging and must be escalated if there is concern of a design/logic flaw or incomplete testing. Imagine your building a rocket to mars and putting you and your family on it. Would you commmit that spaghetti code now?
  2. Every PR should have test coverage unless it is a trivial change or is approved by 2 core team members or designated reviewers.
  3. The BD — upstarter, is a stickler when it comes to architecture, design, code quality, accuracy, comprehensiveness.

Testing Standards

In Progress. Property Testing? Permutation Testing? Join the conversation on The Automata Project Slack Channel

  1. Unit tests test the unit of behavior, not the unit of implementation. Changing the implementation, without changing the behavior or having to change any of your tests is the goal, although not always possible. So where possible, treat your test objects as black boxes, testing through the public API without calling private methods or tinkering with state.

Special notes for Automata developers

  • See ex_doc recommendations for documentation guidelines.
  • DEBUGGING NOTE: anytime you see an error or warning that is in one of the mock sequence modules, it probably isn't. It is probably in one of the modules in core that get injected into them. This is the nature of meta-programming debugging. If anyone with experience debugging a heavily meta-programmed application, please chime in.

Code of Conduct