From b86dc0670783a5e6cbf0c316a236aa5f61be0a9a Mon Sep 17 00:00:00 2001 From: Dmitry Duev Date: Thu, 14 Jan 2021 12:09:15 -0800 Subject: [PATCH] Initialize repository structure (#1) * init repo structure * set up hooks and ci * run ci on main * run ci on main * trigger ci * bla-bla about rebasing -> developer guide * Fritz -> scope --- .flake8 | 16 ++++++++ .pre-commit-config.yaml | 19 ++++++++++ README.md | 4 +- docs/developer.md | 83 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 121 insertions(+), 1 deletion(-) create mode 100644 .flake8 create mode 100644 .pre-commit-config.yaml create mode 100644 docs/developer.md diff --git a/.flake8 b/.flake8 new file mode 100644 index 00000000..817353b4 --- /dev/null +++ b/.flake8 @@ -0,0 +1,16 @@ +# See: +# +# https://pycodestyle.readthedocs.io/en/latest/intro.html#error-codes (E, W) +# https://flake8.pycqa.org/en/latest/user/error-codes.html (F) +# https://github.com/PyCQA/flake8-bugbear +# +# for error codes. And +# +# https://flake8.pycqa.org/en/latest/user/violations.html#selecting-violations-with-flake8 +# +# for error classes selected below. + +[flake8] +max-line-length = 80 +select = C,E,F,W,B,B950 +ignore = E501, W503, E203, W605 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..a08d3cf8 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,19 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v3.3.0 + hooks: + - id: check-yaml + - id: end-of-file-fixer + - id: trailing-whitespace + - repo: https://github.com/python/black + rev: 20.8b1 + hooks: + - id: black + pass_filenames: true + exclude: .ipynb_checkpoints|data| + - repo: https://gitlab.com/pycqa/flake8 + rev: 3.8.4 + hooks: + - id: flake8 + pass_filenames: true + exclude: .ipynb_checkpoints|data|__init__.py diff --git a/README.md b/README.md index b70a8677..494032e9 100644 --- a/README.md +++ b/README.md @@ -1 +1,3 @@ -# scope \ No newline at end of file +# SCoPe: ZTF source classification project + +[Developer guidelines](docs/developer.md) diff --git a/docs/developer.md b/docs/developer.md new file mode 100644 index 00000000..1536d030 --- /dev/null +++ b/docs/developer.md @@ -0,0 +1,83 @@ +# Developer Guidelines + +## How to contribute + +Contributions to `scope` are made through [GitHub Pull Requests](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests), a set of proposed commits (or patches). + +To prepare, you should: + +- Create your own fork the [scope repository](https://github.com/ZwickyTransientFacility/scope) by clicking the "fork" button. + +- [Set up SSH authentication with GitHub](https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh). + +- Clone (download) your copy of the repository, and set up a remote called `upstream` that points to the main `scope` repository. + + ```shell script + git clone git@github.com:/scope + git remote add upstream git@github.com:ZwickyTransientFacility/scope + ``` + +Then, for each feature you wish to contribute, create a pull request: + +1. Download the latest version of `scope`, and create a new branch for your work. + + Here, let's say we want to contribute some documentation fixes; we'll call our branch `rewrite-contributor-guide`. + + ```shell script + git checkout main + git pull upstream main + git checkout -b rewrite-contributor-guide + ``` + +2. Make modifications to `scope` and commit your changes using `git add` and `git commit`. +Each commit message should consist of a summary line and a longer description, e.g.: + + ```text + Rewrite the contributor guide + + While reading through the contributor guide, I noticed several places + in which instructions were out of order. I therefore reorganized all + sections to follow logically, and fixed several grammar mistakes along + the way. + ``` + +3. When ready, push your branch to GitHub: + + ```shell script + git push origin rewrite-contributor-guide + ``` + + Once the branch is uploaded, GitHub should print a URL for turning your branch into a pull request. + Open that URL in your browser, write an informative title and description for your pull request, and submit it. + +4. The team will now review your contribution, and suggest changes. +*To simplify review, please limit pull requests to one logical set of changes.* +To incorporate changes recommended by the reviewers, commit edits to your branch, and push to the branch again +(there is no need to re-create the pull request, it will automatically track modifications to your branch). + +5. Sometimes, while you were working on your feature, the `main` branch is updated with new commits, potentially +resulting in conflicts with your feature branch. The are two ways to resolve this situation - merging and rebasing, +please look [here](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) for a detailed discussion. +While both ways are acceptable, we prefer the second option: + + ```shell script + git checkout rewrite-contributor-guide git rebase upstream/master + ``` + +6. Once the pull request has been reviewed and approved by at least two team members, it will be merged into `scope`. + +## Setting up your environment + +We use `black` to format the code and `flake8` to verify that code complies with [PEP8](https://www.python.org/dev/peps/pep-0008/). +Please install our pre-commit hook as follows: + + ```shell script + pip install pre-commit + pre-commit install + ``` + +This will check your changes before each commit to ensure that they +conform with our code style standards. We use black to reformat Python +code. + +The pre-commit hook will lint *changes* made to the source.