Plasma Hack Week Documentation

How to Contribute

There are numerous ways to contribute to PlasmaPy, including by providing code and documentation, suggesting and discussing ideas, submitting issues and bug reports, and engaging the broader plasma physics community.

Impostor syndrome disclaimer 1

We want your help. No, really.

There may be a little voice inside your head that is telling you that you’re not ready to be an open source contributor; that your skills aren’t nearly good enough to contribute. What could you possibly offer a project like this one?

We assure you - the little voice in your head is wrong. If you can write code at all, you can contribute code to open source. Contributing to open source projects is a fantastic way to advance one’s coding skills. Writing perfect code isn’t the measure of a good developer (that would disqualify all of us!); it’s trying to create something, making mistakes, and learning from those mistakes. That’s how we all improve, and we are happy to help others learn.

Being an open source contributor doesn’t just mean writing code, either. You can help out by writing documentation, tests, or even giving feedback about the project (and yes - that includes giving feedback about the contribution process). Some of these contributions may be the most valuable to the project as a whole, because you’re coming to the project with fresh eyes, so you can see the errors and assumptions that seasoned contributors have glossed over.

Contributing code or documentation to PlasmaPy

If you see something you’d like to work on amongst our issues, start hacking away on that! However, please announce your intent first in the relevant issue to make sure there is no work duplication.

Please note that PlasmaPy has a Community Code of Conduct.

Issues marked by the community as help wanted mean just that - either they’re good contributions for outsiders or there’s an issue in the ongoing work that requires a second opinion. Please consider these first!

Work on PlasmaPy is done via GitHub, so you’ll need a (free) account. If you are new to git, helpful resources include documentation on git basics and an interactive git tutorial. You must also install git locally on your computer. We highly recommend getting reasonably familiar with git by going through these tutorials or a Software Carpentry workshop prior to making code contributions. Do note that you can usually find help in the PlasmaPy Matrix chatroom.

For actual guidelines for working on PlasmaPy, please see our |contributor guide|.

Towncrier changelog entries

Every pull request should include a changelog entry. Please see changelog/README.rst for instructions.

To summarize, put a file like <PULL REQUEST>.<TYPE>.rst, where <PULL REQUEST> is a pull request number, and <TYPE> is one of breaking, feature, bugfix, doc, removal, trivial. If unsure, ask a maintainer.

Footnotes

1

The imposter syndrome disclaimer was originally written by Adrienne Lowe for a PyCon talk. It was adapted in the README files for MetPy and yt, and was then adapted by PlasmaPy.

Community Code of Conduct

The PlasmaPy community strives to follow the best practices in open source software development. New contributors are encouraged to join the team and contribute to the codebase. We anticipate/encourage a global participation from people with diverse backgrounds, skills, interests, and opinions. We believe that such diversity is critical in ensuring a growth of ideas in our community.

Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

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

We as a community pledge to abide by the following guidelines:

• We pledge to treat all people with respect and provide a harassment- and bullying-free environment, regardless of age, sex, sexual orientation and/or gender identity, disability, physical appearance, body size, race, nationality, ethnicity, religion, and level of experience. In particular, sexual language and imagery, sexist, racist, or otherwise exclusionary jokes are not appropriate.

• We pledge to respect the work of others by recognizing acknowledgment/citation requests of original authors. As authors, we pledge to be explicit about how we want our own work to be cited or acknowledged.

• We pledge to welcome those interested in joining the community, and realize that including people with a variety of opinions and backgrounds will only serve to enrich our community. In particular, discussions relating to pros/cons of various technologies, programming languages, and so on are welcome, but these should be done with respect, taking proactive measure to ensure that all participants are heard and feel confident that they can freely express their opinions.

• We pledge to welcome questions and answer them respectfully, paying particular attention to those new to the community. We pledge to provide respectful criticisms and feedback in forums, especially in discussion threads resulting from code contributions.

• We pledge to be conscientious of the perceptions of the wider community and to respond to criticism respectfully. We will strive to model behaviors that encourage productive debate and disagreement, both within our community and where we are criticized. We will treat those outside our community with the same respect as people within our community.

• We pledge to work from the very beginning of this project to make PlasmaPy accessible to people with disabilities.

• We pledge to help the entire community follow these guidelines, and to not remain silent when we see violations of them. We will take action when members of our community violate these guidelines. Members of the PlasmaPy community may contact any member of the Coordinating Committee to report violations. Members of the Coordinating Committee will treat these reports in the strictest confidence. The Coordinating Committee will develop formal procedures for how to handle reported violations.

Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers 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, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting Nick Murphy at namurphy@cfa.harvard.edu or any member of the Coordinating Committee. 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. Project team members should recuse themselves from enforcement of the code of conduct for a given incident if they have an actual or apparent conflict of interest. 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

Parts of these guidelines have been adapted from the Contributor Covenant (version 1.4), the Astropy Community Code of Conduct, and the Python Software Foundation code of conduct.

Formulary (hack.formulary)

hack.formulary provides theoretical formulas for calculation of physical quantities helpful for plasma physics.

API

Authors and Credits

Plasma Hack Week Contributors

The people in the following list have contributed to the Plasma Hack Week repository for 2022. Included in parentheses are ORCID author identifiers.

• Erik Everson

• Nick Murphy (0000-0001-6628-8033)

Bibliography

1

S. J. Buchsbaum. Resonance in a plasma with two ion species. The Physics of Fluids, 3(3):418–420, 1960. URL: https://aip.scitation.org/doi/abs/10.1063/1.1706052, doi:10.1063/1.1706052.

2

S. T. Vincena, W. A. Farmer, J. E. Maggs, and G. J. Morales. Investigation of an ion-ion hybrid alfvén wave resonator. Physics of Plasmas, 20(1):012111, 2013. URL: https://doi.org/10.1063/1.4775777, doi:10.1063/1.4775777.

Glossary

args

An abbreviation for positional arguments.

keyword-only

An argument or parameter is keyword-only when the argument must be provided with the name of the corresponding parameter.

If z is a keyword-only parameter to f(z), then the argument 2 can be provided as f(z=2) but not f(2).

kwargs

An abbreviation for keyword arguments.