added contribution guide

calebweinreb · Feb 23, 2024 · 3d353df · 3d353df
1 parent fdc36a6
commit 3d353df
Show file tree

Hide file tree

Showing 5 changed files with 70 additions and 68 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,34 @@
+# How to Contribute to SNUB
+
+We welcome contributions to SNUB! These can take the form of bug reports, feature requests, or code contributions, as described below.
+
+## Bug reports and feature requests
+
+Please submit bug reports and feature requests as [GitHub issues](https://github.com/calebweinreb/SNUB/issues/new). When submitting a bug report, please include:
+
+- A clear description of the problem
+- Steps to reproduce the problem
+- Your operating system and SNUB version
+
+When submitting a feature request, please include:
+
+- A clear description of the feature
+- A use case for the feature
+
+## Code contributions
+
+Before diving into code contributions, please get in touch so we can ensure that your work will be useful and well-integrated with the rest of the project. You can reach us by opening a [GitHub issue](https://github.com/calebweinreb/SNUB/issues/new) or by emailing [email protected].
+
+### Setting up a development environment
+
+1. Create a fork of the SNUB repository on GitHub and clone it to your computer.
+2. Follow the [installation instructions](https://snub.readthedocs.io/en/latest/install.html) to create a new conda environment.
+3. Navigate to the root of the SNUB repository and run `pip install -e .[dev]` to install SNUB in editable mode along with the development dependencies.
+
+### Making changes
+
+1. Create a new branch for your changes.
+2. Make sure that the tests pass by running `pytest` in the root of the repository.
+3. Format the code by running `black .` in the root of the repository.
+4. Push your changes to your fork and open a pull request. The pull request should go from the branch you created to the `main` branch of the SNUB repository. Make sure to include a clear description of your changes, their motivation, and any relevant information about testing the new features.
+
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -12,14 +12,15 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../../'))
+
+sys.path.insert(0, os.path.abspath("../../"))
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'snub'
-copyright = '2022, Caleb Weinreb'
-author = 'Caleb Weinreb'
+project = "snub"
+copyright = "2022, Caleb Weinreb"
+author = "Caleb Weinreb"
 
 
 # -- General configuration ---------------------------------------------------
@@ -28,16 +29,17 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-	'sphinx.ext.autodoc',
-	'sphinx.ext.napoleon',
-	'sphinx.ext.autosummary',
-	'sphinx.ext.viewcode',
-	'sphinx.ext.coverage',
-	'sphinx.ext.autosectionlabel']
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.coverage",
+    "sphinx.ext.autosectionlabel",
+]
 
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -50,16 +52,15 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-html_favicon = '../media/favicon.png'
+html_static_path = ["_static"]
 
-def setup(app):
-    app.add_css_file('css/custom.css')  # may also be an URL
+html_favicon = "../media/favicon.png"
 
 
+def setup(app):
+    app.add_css_file("css/custom.css")  # may also be an URL
diff --git a/setup.cfg b/setup.cfg
@@ -43,6 +43,7 @@ install_requires =
 [options.extras_require]
 dev = 
     pytest
+    black
     pytest-qt
     sphinx==4.4.0
     sphinx_rtd_theme==1.0.0

diff --git a/snub/_version.py b/snub/_version.py
@@ -70,9 +70,7 @@ def decorate(f):
     return decorate
 
 
-def run_command(
-    commands, args, cwd=None, verbose=False, hide_stderr=False, env=None
-):
+def run_command(commands, args, cwd=None, verbose=False, hide_stderr=False, env=None):
     """Call the given command(s)."""
     assert isinstance(commands, list)
     process = None
@@ -266,9 +264,7 @@ def git_pieces_from_vcs(tag_prefix, root, verbose, runner=run_command):
     env.pop("GIT_DIR", None)
     runner = functools.partial(runner, env=env)
 
-    _, rc = runner(
-        GITS, ["rev-parse", "--git-dir"], cwd=root, hide_stderr=not verbose
-    )
+    _, rc = runner(GITS, ["rev-parse", "--git-dir"], cwd=root, hide_stderr=not verbose)
     if rc != 0:
         if verbose:
             print("Directory %s not under git control" % root)
@@ -303,9 +299,7 @@ def git_pieces_from_vcs(tag_prefix, root, verbose, runner=run_command):
     pieces["short"] = full_out[:7]  # maybe improved later
     pieces["error"] = None
 
-    branch_name, rc = runner(
-        GITS, ["rev-parse", "--abbrev-ref", "HEAD"], cwd=root
-    )
+    branch_name, rc = runner(GITS, ["rev-parse", "--abbrev-ref", "HEAD"], cwd=root)
     # --abbrev-ref was added in git-1.6.3
     if rc != 0 or branch_name is None:
         raise NotThisMethod("'git rev-parse --abbrev-ref' returned error")
@@ -354,9 +348,7 @@ def git_pieces_from_vcs(tag_prefix, root, verbose, runner=run_command):
         mo = re.search(r"^(.+)-(\d+)-g([0-9a-f]+)$", git_describe)
         if not mo:
             # unparsable. Maybe git-describe is misbehaving?
-            pieces["error"] = (
-                "unable to parse git-describe output: '%s'" % describe_out
-            )
+            pieces["error"] = "unable to parse git-describe output: '%s'" % describe_out
             return pieces
 
         # tag
@@ -385,9 +377,7 @@ def git_pieces_from_vcs(tag_prefix, root, verbose, runner=run_command):
         pieces["distance"] = len(out.split())  # total number of commits
 
     # commit date: see ISO-8601 comment in git_versions_from_keywords()
-    date = runner(GITS, ["show", "-s", "--format=%ci", "HEAD"], cwd=root)[
-        0
-    ].strip()
+    date = runner(GITS, ["show", "-s", "--format=%ci", "HEAD"], cwd=root)[0].strip()
     # Use only the last line.  Previous lines may contain GPG signature
     # information.
     date = date.splitlines()[-1]
@@ -475,9 +465,7 @@ def render_pep440_pre(pieces):
     if pieces["closest-tag"]:
         if pieces["distance"]:
             # update the post release segment
-            tag_version, post_version = pep440_split_post(
-                pieces["closest-tag"]
-            )
+            tag_version, post_version = pep440_split_post(pieces["closest-tag"])
             rendered = tag_version
             if post_version is not None:
                 rendered += ".post%d.dev%d" % (
@@ -666,9 +654,7 @@ def get_versions():
     verbose = cfg.verbose
 
     try:
-        return git_versions_from_keywords(
-            get_keywords(), cfg.tag_prefix, verbose
-        )
+        return git_versions_from_keywords(get_keywords(), cfg.tag_prefix, verbose)
     except NotThisMethod:
         pass
 

diff --git a/versioneer.py b/versioneer.py
@@ -432,9 +432,7 @@ def decorate(f):
     return decorate
 
 
-def run_command(
-    commands, args, cwd=None, verbose=False, hide_stderr=False, env=None
-):
+def run_command(commands, args, cwd=None, verbose=False, hide_stderr=False, env=None):
     """Call the given command(s)."""
     assert isinstance(commands, list)
     process = None
@@ -1261,9 +1259,7 @@ def git_pieces_from_vcs(tag_prefix, root, verbose, runner=run_command):
     env.pop("GIT_DIR", None)
     runner = functools.partial(runner, env=env)
 
-    _, rc = runner(
-        GITS, ["rev-parse", "--git-dir"], cwd=root, hide_stderr=not verbose
-    )
+    _, rc = runner(GITS, ["rev-parse", "--git-dir"], cwd=root, hide_stderr=not verbose)
     if rc != 0:
         if verbose:
             print("Directory %s not under git control" % root)
@@ -1298,9 +1294,7 @@ def git_pieces_from_vcs(tag_prefix, root, verbose, runner=run_command):
     pieces["short"] = full_out[:7]  # maybe improved later
     pieces["error"] = None
 
-    branch_name, rc = runner(
-        GITS, ["rev-parse", "--abbrev-ref", "HEAD"], cwd=root
-    )
+    branch_name, rc = runner(GITS, ["rev-parse", "--abbrev-ref", "HEAD"], cwd=root)
     # --abbrev-ref was added in git-1.6.3
     if rc != 0 or branch_name is None:
         raise NotThisMethod("'git rev-parse --abbrev-ref' returned error")
@@ -1349,9 +1343,7 @@ def git_pieces_from_vcs(tag_prefix, root, verbose, runner=run_command):
         mo = re.search(r"^(.+)-(\d+)-g([0-9a-f]+)$", git_describe)
         if not mo:
             # unparsable. Maybe git-describe is misbehaving?
-            pieces["error"] = (
-                "unable to parse git-describe output: '%s'" % describe_out
-            )
+            pieces["error"] = "unable to parse git-describe output: '%s'" % describe_out
             return pieces
 
         # tag
@@ -1380,9 +1372,7 @@ def git_pieces_from_vcs(tag_prefix, root, verbose, runner=run_command):
         pieces["distance"] = len(out.split())  # total number of commits
 
     # commit date: see ISO-8601 comment in git_versions_from_keywords()
-    date = runner(GITS, ["show", "-s", "--format=%ci", "HEAD"], cwd=root)[
-        0
-    ].strip()
+    date = runner(GITS, ["show", "-s", "--format=%ci", "HEAD"], cwd=root)[0].strip()
     # Use only the last line.  Previous lines may contain GPG signature
     # information.
     date = date.splitlines()[-1]
@@ -1503,9 +1493,7 @@ def versions_from_file(filename):
 def write_to_version_file(filename, versions):
     """Write the given version number to the given _version.py file."""
     os.unlink(filename)
-    contents = json.dumps(
-        versions, sort_keys=True, indent=1, separators=(",", ": ")
-    )
+    contents = json.dumps(versions, sort_keys=True, indent=1, separators=(",", ": "))
     with open(filename, "w") as f:
         f.write(SHORT_VERSION_PY % contents)
 
@@ -1591,9 +1579,7 @@ def render_pep440_pre(pieces):
     if pieces["closest-tag"]:
         if pieces["distance"]:
             # update the post release segment
-            tag_version, post_version = pep440_split_post(
-                pieces["closest-tag"]
-            )
+            tag_version, post_version = pep440_split_post(pieces["closest-tag"])
             rendered = tag_version
             if post_version is not None:
                 rendered += ".post%d.dev%d" % (
@@ -1946,9 +1932,7 @@ def run(self):
             # now locate _version.py in the new build/ directory and replace
             # it with an updated value
             if cfg.versionfile_build:
-                target_versionfile = os.path.join(
-                    self.build_lib, cfg.versionfile_build
-                )
+                target_versionfile = os.path.join(self.build_lib, cfg.versionfile_build)
                 print("UPDATING %s" % target_versionfile)
                 write_to_version_file(target_versionfile, versions)
 
@@ -1975,9 +1959,7 @@ def run(self):
             # it with an updated value
             if not cfg.versionfile_build:
                 return
-            target_versionfile = os.path.join(
-                self.build_lib, cfg.versionfile_build
-            )
+            target_versionfile = os.path.join(self.build_lib, cfg.versionfile_build)
             if not os.path.exists(target_versionfile):
                 print(
                     f"Warning: {target_versionfile} does not exist, skipping "
@@ -2192,9 +2174,7 @@ def do_setup():
         configparser.NoOptionError,
     ) as e:
         if isinstance(e, (OSError, configparser.NoSectionError)):
-            print(
-                "Adding sample versioneer config to setup.cfg", file=sys.stderr
-            )
+            print("Adding sample versioneer config to setup.cfg", file=sys.stderr)
             with open(os.path.join(root, "setup.cfg"), "a") as f:
                 f.write(SAMPLE_CONFIG)
         print(CONFIG_ERROR, file=sys.stderr)