Contributing

We need your help This section walks you through how to become a SImSiT developer. 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 or documentation, you can contribute code to open source. Contributing to open source projects is a fantastic way to advance one’s coding and open source workflow 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.

Note

This text was originally written by Adrienne Lowe for a PyCon talk, and was adapted by popclass based on its use in the README file for the MetPy project and Astropy project.

Code of conduct

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

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 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 SImSiT project or its community. Examples of representing the 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 the project may be further defined and clarified by SImSiT maintainers.

Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the LLNL GitHub Admins at github-admin@llnl.gov. The project team will review and investigate all complaints, and will respond in a way that it deems 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 or organization’s leadership.

Note

This Code of Conduct is adapted from the Contributor Covenant version 1.4 and the ssapy code of conduct.

Developer workflow

To add or change code on SImSiT we use Git and GitHub. The normal develop workflow is to branch off main, commit and push changes, and then merge into the main branch with a pull request. Finally, after the pull request has been approved and your changes have been merged you can delete your branch.

Starting from scratch, the typical development workflow would be the following.

  1. Clone the SImSiT Git repository

git clone https://github.com/LLNL/SImSiT.git

  1. Create your own branch with the following naming convention.

git checkout -b -<one or two word description of what you are doing>

For example, if wanted to contribute to documentation your branch might be called docs.

  1. Set the remote of your new branch to GitHub.

git push --set-upstream origin <your branch name>

This means you can push changes to GitHub where they can be saved before you are ready for a pull request. Now you can make your changes and additions to the code and push changes to GitHub.

4. Next go to to the SImSiT GitHub repository page and go to the pull requests tab. Then open a new draft pull request.

  1. Create a pull request with your branch and main.

6. Fill in the title and describe what you are trying to do in the description, and open a draft pull request.

7. As you commit and push changes to your branch on GitHub they will show up in the draft pull request. On every commit some checks will be performed on your code.

The Continuous integration test checks if any of the code you changed failed any of the SImSiT tests. All checks must pass for your code changes if you want them to be accepted!

When you are a happy for you changes to be reviewed and then eventually merged into main, click ready for review. Your code will now be reviewed and when it is accepted it will be merged into main.

8. After your branch has been merged, delete the branch from your local repository.

git branch -d <your branch name>

  1. Then delete the branch from GitHub.

git push -d origin <your branch name>

To start work on a new feature, re-follow the developer workflow from step 2.

New dependencies

If any of your chages require new or updated package dependancies update the requirements.txt file and Dockerfile acordinginly.

What to work on?

So you’ve read the developer guide, now you want to know what exactly to work on. The best place to start is the issues tab on the SImSiT GitHub page. Here you will find a list of tasks that need to be worked on for SImSiT. If you find a bug or would like to request a feature please open a new issue.