Contributing

If you are a Nion Swift user or developer, there are many ways to contribute to the project.

Reporting Issues and Feature Requests

• File issues for bugs or feature requests
• Comment on existing issues with pertinent information
• Isolate problems with UI, features, or performance and write tests
• Contribute source code

If you are submitting an issue, please try to answer these common questions.

• Is your issue focused on one particular thing? Please avoid listing multiple requests in a single issue unless they are fundamentally related.
• Have you searched the issues (open and closed) for the same or related issues? Often the issue or feature you're reporting will already be entered.
• What version of Swift are you running? You should try to reproduce the bug on the latest released Swift version if possible.
• How has Swift been installed? From drag and drop? PyPI? Conda?
• What is the underlying Python environment? What version of Python?
• What packages is Swift running? For instance, are you running acquisition?
• How can the issue be reproduced? Please provide as much information as possible for us to reproduce the issue.
• Can this be reproduced on a new minimal project file?

For performance issues.

• What are the specs of the machine (CPU/memory/storage-type)?
• Is there a particular action that seems particularly sluggish?
• Is it always sluggish (i.e. immediately after launch) or does it slowly get worse?

Feature Requests

If you have an idea for a new feature, start by searching the issue tracker (both open and closed issues) for similar requests.

Explain the rationale for the feature you're requesting. Why would this feature be useful? Consider also any possible drawbacks, including backwards compatibility, new library dependencies, and performance issues.

We recommend that you discuss a potential new feature on the issue tracker or Nion Swift discussions before starting work to make sure it fits cleanly into the roadmap.

If entered into the issue tracker, limit the issue to one specific feature, not a list of associated features.

If the feature request is a larger request involving multiple individual features and capabilities, consider writing a specification document and asking for it to be recorded on this wiki site.

Triaging and Prioritization

We will periodically review new and open issues, adding labels, milestones, and assignees to the issue. In addition we will prioritize issues according to the following criteria:

• Prioritize urgent issues first, then important. Prioritize issues with dependencies.
• Prioritize by the value of the issue, as measured by the criteria below or by the number of users affected by the issue.
• Everything else equal, prioritize lengthier tasks first, but be flexible.

We will attempt to assign value to an issue based on various criteria, including:

• Addresses data loss or integrity (urgent)
• Time savings for regular users
• Overall ease of use for regular users
• Addresses performance issue
• Streamlines repetitive tasks
• Simplifies training
• Reduces support issues
• Improves demo or initial impression
• Introduces a new capability
• Time savings for installation
• Customer request
• Bug bounty

Contributing Source Code

Patches and pull requests are welcome. Before you put time into a nontrivial patch, it is a good idea to discuss it on GitHub Issues, especially if it is for a new feature (rather than fixing a bug).

If you are contributing source code, please be aware of the following decision points.

• Can you implement your custom code using the Nion Swift public API? If so, this is the good way to have custom code that will be compatible with future versions.
• Does your custom code belong in Nion Swift or one of its extension packages? For instance, almost all acquisition related code would go into a specific extension such as nionswift-instrumentation-kit or even something more specific.
• Does your custom code require the internal Nion Swift API? If so, this will be difficult to maintain over time. You should file issues requesting public API to be extended to accommodate your custom code.
• Does you custom code require internal access to Nion Swift and is it something that would appeal to a wide range of users? If so, you should get your code into a well documented state and create a pull request to have it integrated into the base project.
• Are you willing to agree to the licensing terms for contributions? User facing code is typically released on GPLv3 and library/processing code is typically released on Apache license. However, Nion reserves the right to make licensing changes to ensure the longer term survival of the project.

Pull Request Guidelines

If you are submitting a pull request, you can expect the following.

• The Nion Swift code base has very specific code formatting and documentation requirements. At a minimum, your code should be well typed and pass mypy verification tool if they are enabled for the files you are changing.
• The code base has purposely limited upstream requirements (e.g. numpy, scipy) and your code should typically not depend on any Python package not already included. This can be discussed on a case by case basis, but the bar is high for inclusion of a new dependency.
• Any code that affects the file format in any way will receive extra strict scrutiny and be evaluated as to its fitness as a long term change. This includes any new objects that get written into the file system. Backwards and forwards compatibility are of the utmost importance.
• Forward compatibility includes features, architecture, objects, file formats, protocols, designs, etc. All are expected to be available for several years. Your code will be evaluated with that perspective in mind.
• Your code must pass existing regression tests on all supported platforms and configurations with minimal modifications to existing tests and must include reasonable test cases for its own new behavior. The continuous integration (CI) tests will automatically test this for any pull requests (PRs).
• Your code must pass existing strict typing as determined by mypy. The typing should be as specific as possible (i.e. limited use of typing.Any).
• If your code is rejected, we may suggest expanding the public API so that your code can be accommodated as an extension package.
• Each commit should focus on one specific change and should not include extraneous formatting changes. Commit messages should follow the standard Git commit format (one line up to approx. 100 characters, followed by blank line, followed by explanation split into 100 character lines). If the commit completely fixes an issue, it should include the "Fix #. " at the beginning of the first line of the commit message, e.g. "Fix #33. Fix issue with high DPI displays." Reference: Write Better Commits, Build Better Projects
• Add tests for your code. Tests for a bug fix should fail without your code and succeed with your code. Tests for features should cover basic behavior and highlight how the code is expected to work. We generally write tests when things fail; but including some initial tests is also useful.
• Update the user guide if your change affects user interface that is already explained in the user guide.
• Follow the stylistic conventions you find in the existing code. Use spaces, not tabs. Use Unix line endings (LF).
• Be sure to trim whitespace from PR's.

Coding Style

Good code is written so that is readable, understandable, covered by automated tests, not over complicated and does well what is intended to do.

• Follow the coding style of the existing code as much as possible
• Write comments to explain why, not how (let the code do that).
• Avoid reformatting code just for the sake of reformatting; it makes review and diff difficult.
• Review changes carefully before committing.
• Write good commit messages (guide1, guide2).
• Always commit with Unix-style line endings.
• Avoid using abbreviations for variables or function names. Taming Names
• Try to write functions and methods with zero side effects.
• Integration tests are useful to verify behavior, but also to notice changes in behavior.
• Write tests by exception, i.e. add test when something fails unexpectedly.
• Make instance variables private when possible.
• Avoid using global variables.
• Use double quotes and gettext or _ for UI strings.
• Use get/set properties when there are few side effects of setting property.
• Name methods with an action, not a noun; name properties with a noun.
• Avoid using explicit reference counting or close methods when possible. Explore how finalize is used in existing library.
• Write close methods to minimize errors:
  • When an object is closed, null it out so it isn’t accidentally re-used.
  • Write tests to make sure anything using an object with a close method calls close.
  • Close methods should set all variables to None for garbage collection.
  • Canvas items will be closed if their parent is closed.