Skip to content

Home

Jump to bottom
Aranildo edited this page Mar 18, 2025 · 2 revisions

Welcome to the nc2pt wiki! Here you can find information about the project and also some guidelines of how to contribute.

Contribution Guide

The information about how to contribute to this project was based on several websites, other projects and links. This documentation is a working in progress and suggestions to the process are welcome.

Submitting a bug report or a feature request

We use GitHub issues to track all bugs and feature requests; feel free to open an issue if you have found a bug or wish to see a feature implemented.

Opening an issue

Ideally any change to the code should have a linked issue. This includes new features, code optimization or refactor, bugs, etc. You should usually open an issue in the following situations:

  • Report an error
  • Discuss a high-level topic or idea (for example, community, vision or policies)
  • Propose a new feature or other project idea

It is recommended to check that your issue complies with the following rules before submitting:

  • Verify that your issue is not being currently addressed by other issues or pull requests.
  • If you are submitting a new feature request, please describe as much as you can what you would like in the issue you will open.
  • If you are submitting a bug report, we strongly encourage you to follow the guidelines in How to make a good bug report

Also here are some tips for communicating on issues:

  • If you see an open issue that you want to tackle, comment on the issue to let people know you’re on it. That way, people are less likely to duplicate your work.
  • If an issue was opened a while ago, it’s possible that it’s being addressed somewhere else, or has already been resolved, so comment to ask for confirmation before starting work.
  • If you opened an issue, but figured out the answer later on your own, comment on the issue to let people know, then close the issue. Even documenting that outcome is a contribution to the project.

How to make a good bug report

When you submit an issue related to a bug, please do your best to follow these guidelines! This will make it a lot easier to provide a good feedback and possible solution:

  • The ideal bug report contains a short reproducible code snippet, this way anyone can try to reproduce the bug easily. If your snippet is longer than around 50 lines, please link to a Gist or a GitHub repo.
  • If not feasible to include a reproducible snippet, please be specific about what functions are involved.
  • If an exception is raised, please provide the full traceback.
  • Please ensure all code snippets and error messages are formatted in appropriate code blocks. See Creating and highlighting code blocks for more details.

How to contribute

Writing Clean Python Code

To maintain readability and consistency, follow clean code principles based on PEP 8. This would not be enforced but it is a very good practice to follow. Some examples are:

  • Use meaningful variable and function names.
  • Keep functions short and focused on a single task.
  • The arguments in your function should be kept to a minimum.
  • Use list comprehensions where appropriate.
  • Write docstrings for functions and classes.
  • Follow Python's naming conventions (snake_case for variables and functions, PascalCase for classes).
  • Don't use "magic numbers" (strange numbers that appear in code, which do not have a clear meaning).

For more details, refer to: Clean Code for Python Users

Open a pull request

The preferred way to contribute to the project is to fork the main repository on GitHub, then submit a “pull request” (PR).

If the project is on GitHub, here’s how to submit a pull request:

  • Create a branch for your edits.
  • Reference any relevant issues or supporting documentation in your PR (for example, “Closes #37.”)
  • Include screenshots of the before and after if your changes include differences in plots for example. Drag and drop the images into the body of your pull request.
  • Test your changes! Run your changes against any existing tests if they exist and create new ones when needed. It’s important to make sure your changes don’t break the existing project.
  • Contribute in the style of the project to the best of your abilities. This may mean using indents, semi-colons or comments differently than you would in your own repository, but makes it easier for the maintainer to merge, others to understand and maintain in the future.

ATTENTION: Forking the repository and cloning it locally are regular procedures on github. Because the number of contributors right now is fairly small and also to avoid extra bureaucracy, this step is not being used. Therefore, contributors should be careful when merging branches to the main repo.

Suggested Workflow for Contributing

To ensure smooth collaboration and avoid common Git conflicts, follow this process:

1. Create an Issue

  • If you find a bug, want to add a feature, or improve the code, create an issue first.
  • All issues and pull requests on the issue tracker should have (at least) one tag. For instance, Bug (something is happening that clearly shouldn’t happen, wrong results as well as unexpected errors), enhancement (improving performance, usability, consistency), new feature (feature requests and pull requests implementing a new feature).
  • Refer to: Creating an Issue

2. Sync Local Branch with Master

3. Create a Branch for the Issue

4. Make Changes and Commit

  • Implement the changes required for the issue.
  • When committing, include Close #issuenumber in the commit message to automatically close the issue when merged.
  • Refer to: Linking a Pull Request to an Issue

5. Push Changes to Remote Repository

  • Push the committed changes, which will prompt a message about a possible merge request.

6. Create a Merge Request (Pull Request)

7. Code Review and Merging

  • If working in a team, ALWAYS request another contributor to review and merge your changes. The reviewer does not need to know in depth all the changes you made, but it is always good to have another pair of eyes checking the code.
  • If working alone, review your code thoroughly before merging.

8. Repeat as Needed 😊

Additional Resources

Clone this wiki locally