How To Contribute

Thank you for considering to contribute to Foundry! People like yourself are the lifeblood of the community and this tool.

The purpose of this document is to codify the processes required to contribute to this project to empower yourself and the community to contribute.

Support

If GitHub is overwhelming, but still want to help the community: help fellow developers on StackOverflow [1].

The official tag is python-foundry and support enables us to improve Foundry instead.

Also, if development is not your forte, you can also help the game design community over at Discord [2].

Getting Started

You will need a working version of Python between the versions specified inside the toml file. To install the remaining dependencies, simply write the following:

$ git clone git@github.com:TheJoeSmo/Foundry.git
$ cd Foundry
$ pip install -r requirements-dev.txt
$ python -m foundry.main

This will install the remaining dependencies. It is recommended to run this command after each fetch or update to the project’s dependencies, as it ensures the continuos integration environment is equivalent to your local one.

If everything worked, you should be able to run the following and see that every test passed:

$ python -m pytest

Workflow

• No contribution is too small! Fixes to typos and grammar are welcome.

• Try to limit each pull request to a single change.

• Always add tests and documentation for your code. We recommend using test driven development to develop your software [4]. It helps divide the program into smaller parts, which helps both yourself and the reviewer. If either tests or documentation are not provided, your code will be ineligible to be merged.

• Make sure that your new tests would otherwise fail without your change.

• Ensure that your new test and the remaining tests pass using PyTest. When making a pull request, Github will automatically run these tests. We will not provide feedback until all tests pass or explicitly asked.

• Once you’ve addressed review feedback, make sure to bump the pull request with a small note so we know you have finished.

Code

• Obey PEP 8 and Numpy Docs style guide [5] [6]. We use """ for on separate lines for doc-strings.

  from typing import ClassVar
  
  from attr import attrs
  
  @attrs(slots=True, auto_attribs=True, eq=True, hash=True, frozen=True)
  class Example:
      """
      This is an example class to showcase the documentation style guidelines as defined by the
      Numpy Doc style guide [1]_.
  
      This is the extended summary.  We try to avoid this, but it acceptable under some
      circumstances.  Instead you should use `Notes` to write specific implementation details
      and so on.  This section should only be used if there is some erroneous details about
      *functionality* that need to be clarified.
  
      Attributes
      ----------
      example: str
          An example attribute.
      version: ClassVar[int]
          The amount of times this class has been updated.
  
      Methods
      -------
      example_method(x: int, y: int = 2) -> str:
          A method to showcase the documentation style guidelines for a function or method.
  
      See Also
      --------
      example_function: This is `example_method` reincarnated as a function, from the same module.
      module.ExtendedExample: This is `Example` but extended into a novel, inside a sub-module.
      foundry.module.ExtendedExtendedExample: Provide the entire path for a different module.
  
      Notes
      -----
      Please notice that `example_method` does not include `self` under `Methods`.
  
      It is advised to only explain private methods this section and any other specific implementation
      detail.
  
      History of the class or method should go here.
  
      References
      ----------
      .. [1] The NumpyDoc style guide: `NumpyDocs <https://numpydoc.readthedocs.io/en/latest/format.html>`_
      """
  
      example: str
  
      version: ClassVar[int] = 2
  
      def example_method(self, x: int, y: int = 2) -> str:
          """
          Do something.
  
          Parameters
          ----------
          x : int
              Description of parameter `x`.
  
          Returns
          -------
          str
              Description of the string return value.
  
          Raises
          ------
          Sadness
              When someone does not document.
  
          Examples
          --------
          >>> Example().example_method(0)
          This is an example
  
          Brace yourself for the second example...  You won't expect it.
  
          >>> Example().example_method(1)
          The Spanish Inquisition
          """
          pass
  

• We use Black, Flake8, and Isort as our linters. We recommend you set run the following commands before making a pull request. Fortunately, we have set up a simple method to get everything running by default. Simply run the following and these checks will be ran before every pull request.

  $ python -m pip install pre-commit
  $ pre-commit install
  

  or for Linux users:

  $ python3 -m pip install pre-commit
  $ pre-commit install
  

  You can also run them anytime using the following command:

  $ pre-commit run --all-files
  

  Notes:

  Depending on your shell you may run into a problem where pre-commit is not found. This is because the path is found inside ~/.profile. We have provided the most common fixes for bash and zsh [7].

  Bash: Add source ~/.profile inside ~/.bashrc.

  ZHS: Add [[ -e ~/.profile ]] && emulate sh -c 'source ~/.profile' inside ~/.zshrc.

Tests

• Tests should write the asserts as expected == actual, to provide easier readability

• To run the test suite, simply write the following in your console:

  $ python -m pytest
  

References

[1]

StackOverflow: https://stackoverflow.com/questions/tagged/python-nametable

[2]

SMB3 Prime Discord Server: https://discord.gg/MMExJKExGG

[3]

Poetry Installation Guide: https://python-poetry.org/docs/

[4]

Test Driven Development Guide: https://www.youtube.com/watch?v=yfP_v6qCdcs

[5]

PEP 8: https://www.python.org/dev/peps/pep-0008

[6]

NumpyDoc Guide: https://numpydoc.readthedocs.io/en/latest/format.html

[7]

ZSH and Poetry Guide: https://superuser.com/questions/187639/zsh-not-hitting-profile

Contributor Code of Conduct

Our Promise

We as members, contributors, and leaders promise to provide a harrassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge that our interactions will contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to creating a positive environment include:

• Using welcoming and inclusive language

• Being respectful of differing viewpoints and experiences

• Gracefully accepting constructive criticism

• Focusing on what is best for the community

• Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

• The use of sexualized language or imagery and unwelcome sexual attention or advances

• Trolling, insulting/derogatory comments, and personal or political attacks

• Public or private harassment

• Publishing others’ private information, such as a physical or electronic address, without explicit permission

• Other conduct which could reasonably be considered inappropriate in a professional setting

Our Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies both inside the project and in public spaces where an individual is representing the project or its associated community. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at joesmo.joesmo12@gmail.com. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project’s leadership.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>.