From 2bb4d3b78588ff194594aedfa4f10868a7f752ad Mon Sep 17 00:00:00 2001 From: Cheuk Yin Ng Date: Thu, 24 Sep 2020 19:59:56 -0700 Subject: [PATCH 1/7] feat: remove some things --- docs/doc_reqs.txt | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/doc_reqs.txt b/docs/doc_reqs.txt index ed74c6f7..66272337 100644 --- a/docs/doc_reqs.txt +++ b/docs/doc_reqs.txt @@ -4,7 +4,6 @@ APScheduler==3.6.3 astroid==2.4.2 async-timeout==3.0.1 attrs==20.2.0 -awscli==1.18.145 Babel==2.8.0 backcall==0.2.0 boto3==1.15.4 @@ -22,7 +21,6 @@ decorator==4.4.2 Deprecated==1.2.10 docutils==0.15.2 filelock==3.0.12 -flake8==3.8.3 Flask==1.1.2 Flask-Limiter==1.4 flask-talisman==0.7.0 @@ -52,8 +50,6 @@ mccabe==0.6.1 mistune==0.8.4 more-itertools==8.5.0 multidict==4.7.6 -mypy==0.782 -mypy-extensions==0.4.3 oauthlib==3.1.0 packaging==20.4 parso==0.7.1 From e742a88277b6e94afcc65cc15f201fa4a8318b42 Mon Sep 17 00:00:00 2001 From: Cheuk Yin Ng Date: Thu, 24 Sep 2020 20:03:38 -0700 Subject: [PATCH 2/7] feat: use pipenv lock -r --- docs/doc_reqs.txt | 114 ++++++++++++---------------------------------- 1 file changed, 28 insertions(+), 86 deletions(-) diff --git a/docs/doc_reqs.txt b/docs/doc_reqs.txt index 66272337..f01d1bb2 100644 --- a/docs/doc_reqs.txt +++ b/docs/doc_reqs.txt @@ -1,110 +1,52 @@ -aiohttp==3.6.2 -alabaster==0.7.12 -APScheduler==3.6.3 -astroid==2.4.2 -async-timeout==3.0.1 -attrs==20.2.0 -Babel==2.8.0 -backcall==0.2.0 +-i https://pypi.org/simple +aiohttp==3.6.2; python_full_version >= '3.5.3' +apscheduler==3.6.3 +async-timeout==3.0.1; python_full_version >= '3.5.3' +attrs==20.2.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' boto3==1.15.4 botocore==1.18.4 -cachetools==4.1.1 certifi==2020.6.20 cffi==1.14.3 chardet==3.0.4 -click==7.1.2 -codecov==2.1.7 +click==7.1.2; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' colorama==0.4.3 -coverage==5.3 cryptography==3.1.1 -decorator==4.4.2 -Deprecated==1.2.10 -docutils==0.15.2 -filelock==3.0.12 -Flask==1.1.2 -Flask-Limiter==1.4 +deprecated==1.2.10; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' +flask-limiter==1.4 flask-talisman==0.7.0 -google-api-core==1.22.2 -google-api-python-client==1.12.2 -google-auth==1.21.3 -google-auth-httplib2==0.0.4 -google-auth-oauthlib==0.4.1 -googleapis-common-protos==1.52.0 +flask==1.1.2 gunicorn==20.0.4 -httplib2==0.18.1 -idna==2.10 -imagesize==1.2.0 +idna==2.10; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' iniconfig==1.0.1 -ipython==7.18.1 -ipython-genutils==0.2.0 -isort==5.5.3 -itsdangerous==1.1.0 -jedi==0.17.2 -Jinja2==2.11.2 -jmespath==0.10.0 -lazy-object-proxy==1.4.3 +itsdangerous==1.1.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' +jinja2==2.11.2; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' +jmespath==0.10.0; python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3' limits==1.5.1 -m2r==0.2.1 -MarkupSafe==1.1.1 -mccabe==0.6.1 -mistune==0.8.4 -more-itertools==8.5.0 -multidict==4.7.6 -oauthlib==3.1.0 -packaging==20.4 -parso==0.7.1 +markupsafe==1.1.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' +more-itertools==8.5.0; python_version >= '3.5' +multidict==4.7.6; python_version >= '3.5' +packaging==20.4; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' pem==20.1.0 -pexpect==4.8.0 -pickleshare==0.7.5 -pluggy==0.13.1 -prompt-toolkit==3.0.7 -protobuf==3.13.0 -ptyprocess==0.6.0 -py==1.9.0 -pyasn1==0.4.8 -pyasn1-modules==0.2.8 -pycodestyle==2.6.0 -pycparser==2.20 +pluggy==0.13.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' +py==1.9.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' +pycparser==2.20; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' pyee==7.0.4 -pyflakes==2.2.0 -PyGithub==1.53 -Pygments==2.7.1 -PyJWT==1.7.1 -pylint==2.6.0 -pyparsing==2.4.7 +pygithub==1.53 +pyjwt==1.7.1 +pyparsing==2.4.7; python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3' pytest==6.0.2 -pytest-cov==2.10.1 -pytest-mypy==0.7.0 -python-dateutil==2.8.1 +python-dateutil==2.8.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' pytz==2020.1 -PyYAML==5.3.1 requests==2.24.0 -requests-oauthlib==1.3.0 -rsa==4.6 s3transfer==0.3.3 -six==1.15.0 +six==1.15.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' slackclient==2.3.0 slackeventsapi==2.2.1 -snowballstemmer==2.0.0 -Sphinx==3.2.1 -sphinx-autodoc-typehints==1.11.0 -sphinx-rtd-theme==0.5.0 -sphinxcontrib-applehelp==1.0.2 -sphinxcontrib-devhelp==1.0.2 -sphinxcontrib-htmlhelp==1.0.3 -sphinxcontrib-jsmath==1.0.1 -sphinxcontrib-qthelp==1.0.3 -sphinxcontrib-serializinghtml==1.1.4 structlog==20.1.0 toml==0.10.1 -traitlets==5.0.4 -typed-ast==1.4.1 -typing-extensions==3.7.4.3 tzlocal==2.1 -uritemplate==3.0.1 -urllib3==1.25.10 +urllib3==1.25.10; python_version != '3.4' watchtower==0.7.3 -wcwidth==0.2.5 -Werkzeug==1.0.1 +werkzeug==1.0.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' wrapt==1.12.1 -yarl==1.6.0 +yarl==1.6.0; python_version >= '3.5' From 66bab4b56ed55e7efcfb488b3939d2b2667e324f Mon Sep 17 00:00:00 2001 From: Cheuk Yin Ng Date: Thu, 24 Sep 2020 20:05:20 -0700 Subject: [PATCH 3/7] feat: use pipenv lock -r --dev --- docs/doc_reqs.txt | 50 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/doc_reqs.txt b/docs/doc_reqs.txt index f01d1bb2..2573edc3 100644 --- a/docs/doc_reqs.txt +++ b/docs/doc_reqs.txt @@ -1,52 +1,102 @@ -i https://pypi.org/simple aiohttp==3.6.2; python_full_version >= '3.5.3' +alabaster==0.7.12 apscheduler==3.6.3 +astroid==2.4.2; python_version >= '3.5' async-timeout==3.0.1; python_full_version >= '3.5.3' attrs==20.2.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' +awscli==1.18.145 +babel==2.8.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' +backcall==0.2.0 boto3==1.15.4 botocore==1.18.4 certifi==2020.6.20 cffi==1.14.3 chardet==3.0.4 click==7.1.2; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' +codecov==2.1.7 colorama==0.4.3 +coverage==5.3; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' and python_version < '4' cryptography==3.1.1 +decorator==4.4.2 deprecated==1.2.10; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' +docutils==0.15.2; python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3' +filelock==3.0.12 +flake8==3.8.3 flask-limiter==1.4 flask-talisman==0.7.0 flask==1.1.2 gunicorn==20.0.4 idna==2.10; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' +imagesize==1.2.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' iniconfig==1.0.1 +ipython-genutils==0.2.0 +ipython==7.18.1 +isort==5.5.3; python_version >= '3.6' and python_version < '4.0' itsdangerous==1.1.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' +jedi==0.17.2; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' jinja2==2.11.2; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' jmespath==0.10.0; python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3' +lazy-object-proxy==1.4.3; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' limits==1.5.1 +m2r==0.2.1 markupsafe==1.1.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' +mccabe==0.6.1 +mistune==0.8.4 more-itertools==8.5.0; python_version >= '3.5' multidict==4.7.6; python_version >= '3.5' +mypy-extensions==0.4.3 +mypy==0.782 packaging==20.4; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' +parso==0.7.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' pem==20.1.0 +pexpect==4.8.0; sys_platform != 'win32' +pickleshare==0.7.5 pluggy==0.13.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' +prompt-toolkit==3.0.7; python_full_version >= '3.6.1' +ptyprocess==0.6.0 py==1.9.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' +pyasn1==0.4.8 +pycodestyle==2.6.0 pycparser==2.20; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' pyee==7.0.4 +pyflakes==2.2.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' pygithub==1.53 +pygments==2.7.1; python_version >= '3.5' pyjwt==1.7.1 +pylint==2.6.0 pyparsing==2.4.7; python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3' +pytest-cov==2.10.1 +pytest-mypy==0.7.0 pytest==6.0.2 python-dateutil==2.8.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' pytz==2020.1 +pyyaml==5.3.1 requests==2.24.0 +rsa==4.5; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' and python_version < '4' s3transfer==0.3.3 six==1.15.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' slackclient==2.3.0 slackeventsapi==2.2.1 +snowballstemmer==2.0.0 +sphinx-autodoc-typehints==1.11.0 +sphinx-rtd-theme==0.5.0 +sphinx==3.2.1 +sphinxcontrib-applehelp==1.0.2; python_version >= '3.5' +sphinxcontrib-devhelp==1.0.2; python_version >= '3.5' +sphinxcontrib-htmlhelp==1.0.3; python_version >= '3.5' +sphinxcontrib-jsmath==1.0.1; python_version >= '3.5' +sphinxcontrib-qthelp==1.0.3; python_version >= '3.5' +sphinxcontrib-serializinghtml==1.1.4; python_version >= '3.5' structlog==20.1.0 toml==0.10.1 +traitlets==5.0.4; python_version >= '3.7' +typed-ast==1.4.1 +typing-extensions==3.7.4.3 tzlocal==2.1 urllib3==1.25.10; python_version != '3.4' watchtower==0.7.3 +wcwidth==0.2.5 werkzeug==1.0.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' wrapt==1.12.1 yarl==1.6.0; python_version >= '3.5' From 106bae5705c59920810b6b8d494f76ae621cf7c5 Mon Sep 17 00:00:00 2001 From: Cheuk Yin Ng Date: Thu, 24 Sep 2020 20:22:36 -0700 Subject: [PATCH 4/7] fix: monkeypatch m2r to work with current ver of sphinx --- conf.py | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/conf.py b/conf.py index d6f2f15d..bf4e24f7 100644 --- a/conf.py +++ b/conf.py @@ -13,6 +13,7 @@ """ import os import sys +import sphinx sys.path.insert(0, os.path.abspath('.')) @@ -173,6 +174,24 @@ epub_exclude_files = ['search.html'] +def monkeypatch(cls): + """ decorator to monkey-patch methods """ + def decorator(f): + method = f.__name__ + old_method = getattr(cls, method) + setattr(cls, method, lambda self, *args, **kwargs: f(old_method, self, *args, **kwargs)) + return decorator + +# workaround until https://github.com/miyakogi/m2r/pull/55 is merged +@monkeypatch(sphinx.registry.SphinxComponentRegistry) +def add_source_parser(_old_add_source_parser, self, *args, **kwargs): + # signature is (parser: Type[Parser], **kwargs), but m2r expects + # the removed (str, parser: Type[Parser], **kwargs). + if isinstance(args[0], str): + args = args[1:] + return _old_add_source_parser(self, *args, **kwargs) + + # -- Extension configuration ------------------------------------------------- def skip(app, what, name, obj, autoskip, options): """Make sure we don't skip __init__ functions.""" From f3aff87148abcd12915399905c79425ac435acb0 Mon Sep 17 00:00:00 2001 From: Cheuk Yin Ng Date: Thu, 24 Sep 2020 20:45:50 -0700 Subject: [PATCH 5/7] fix: turn all md into rst, because m2r is a bad lib --- CONTRIBUTING.rst | 131 ++++++++++++++ LICENSE.rst | 25 +++ Pipfile | 1 - docs/Config.md | 117 ------------- docs/Config.rst | 135 +++++++++++++++ docs/Database.md | 58 ------- docs/Database.rst | 95 ++++++++++ docs/Deployment.md | 135 --------------- docs/Deployment.rst | 152 ++++++++++++++++ docs/GettingStarted.md | 75 -------- docs/GettingStarted.rst | 80 +++++++++ docs/KarmaCommands.md | 53 ------ docs/KarmaCommands.rst | 64 +++++++ docs/LocalDevelopmentGuide.md | 274 ----------------------------- docs/LocalDevelopmentGuide.rst | 307 +++++++++++++++++++++++++++++++++ docs/ProjectCommands.md | 85 --------- docs/ProjectCommands.rst | 92 ++++++++++ docs/Qna.md | 19 -- docs/Qna.rst | 18 ++ docs/Requirements.md | 39 ----- docs/Requirements.rst | 49 ++++++ docs/Scheduler.md | 61 ------- docs/Scheduler.rst | 69 ++++++++ docs/Scripts.md | 139 --------------- docs/Scripts.rst | 157 +++++++++++++++++ docs/TeamCommands.md | 116 ------------- docs/TeamCommands.rst | 128 ++++++++++++++ docs/Testing.md | 58 ------- docs/Testing.rst | 68 ++++++++ docs/UserCommands.md | 77 --------- docs/UserCommands.rst | 85 +++++++++ index.rst | 32 ++-- 32 files changed, 1671 insertions(+), 1323 deletions(-) create mode 100644 CONTRIBUTING.rst create mode 100644 LICENSE.rst delete mode 100644 docs/Config.md create mode 100644 docs/Config.rst delete mode 100644 docs/Database.md create mode 100644 docs/Database.rst delete mode 100644 docs/Deployment.md create mode 100644 docs/Deployment.rst delete mode 100644 docs/GettingStarted.md create mode 100644 docs/GettingStarted.rst delete mode 100644 docs/KarmaCommands.md create mode 100644 docs/KarmaCommands.rst delete mode 100644 docs/LocalDevelopmentGuide.md create mode 100644 docs/LocalDevelopmentGuide.rst delete mode 100644 docs/ProjectCommands.md create mode 100644 docs/ProjectCommands.rst delete mode 100644 docs/Qna.md create mode 100644 docs/Qna.rst delete mode 100644 docs/Requirements.md create mode 100644 docs/Requirements.rst delete mode 100644 docs/Scheduler.md create mode 100644 docs/Scheduler.rst delete mode 100644 docs/Scripts.md create mode 100644 docs/Scripts.rst delete mode 100644 docs/TeamCommands.md create mode 100644 docs/TeamCommands.rst delete mode 100644 docs/Testing.md create mode 100644 docs/Testing.rst delete mode 100644 docs/UserCommands.md create mode 100644 docs/UserCommands.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..636e19db --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,131 @@ +Contributing +============ + +This document contains important details for anyone contributing to +Rocket 2. + +Opening an Issue +---------------- + +If you see a bug or have a feature request, please `open an +issue `__! That being +said, make sure to do a quick search first - there may already be an +issue that covers it. + +When creating a new issue, please add a label describing the issue; the +most relevant are probably “Bug” and “Feature request”. + +**If you are going to work on an issue, please assign yourself to it, +and unassign yourself if you stop working on it.** + +If you are not planning to work on a new issue, please also add it to +the Rocket 2.0 project; this will automatically add it to our Kanban +board’s backlog, where we can review it in a future sprint. + +Setting up branches +------------------- + +Before you make any changes, you should first set up your own branch. It +is common convention to name your branch: + +:: + + /#- + +So if your issue is `#153 Read from +configuration `__, +you would name it ``rwblickhan/#153-read-from-config``. The name needs +to be concise, descriptive, and, well, have your name and number, so to +speak. + +Before-Pull-Request checklist +----------------------------- + +- All tests and style and docs checks pass (``scripts/build_check.sh``) +- The Github build passes (Github will build your commit when you push + it) +- Your code is presentable and you have **not** committed extra files + (think your credentials, IDE config files, cached directories, build + directories, etc.) +- You’ve written unit tests for the changes you’ve made, and that they + cover all the code you wrote (or effectively all, given the + circumstances) + +We use ``codecov`` to check code coverage, but you can easily check the +code coverage using the ``scripts/build_check.sh`` script. The coverage +should be displayed after the unit tests are run. + +Submitting a Pull Request +------------------------- + +We appreciate pull requests of any size or scope. + +Please use a clear, descriptive title for your pull request and fill out +the pull request template with as much detail as you can. In particular, +all pull requests should be linked to one or more issues - if a relevant +issue does not exist, please create one as described above. + +All pull requests must be code reviewed. Currently the code is owned by +the +`brussel-sprouts `__ +team at UBC Launch Pad; at least one member of the team must approve the +pull request before it can be merged. + +All pull requests must pass our Github build before they can be merged. +The Github build checks for: + +- Passing unit tests (via `pytest `__) +- Minimum code coverage of unit tests (via + `Codecov.io `__) +- Code linting (via + `flake8 `__) +- PEP8 code style (via + `pycodestyle `__) +- Correctly-formatted docstrings (via + `pydocstyle `__) +- Correctly-formatted Markdown documentation (via + `mdl `__) + +All of these checks are conveniently done using the +``scripts/build_check.sh`` as mentioned above. + +Remember to add the label ``Ready for Review``. + +After your pull request has been approved and the Github build passes, +it can be merged into ``master``. Please do so with an ordinary merge +commit, not a rebase or squash merge. + +Work in progress (WIP) pull requests +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes, it may be more appropriate to submit a pull request that you +are working on, just to say that you are working on something (or so +that you can get some initial feedback on your work). In that case, it +can be a good idea to submit a pull request marked WIP. The convention +here is to prepend ``[WIP]`` in the title of the request, and to further +mark it with the label ``WIP``. + +Updating an Outdated Pull Request +--------------------------------- + +If changes have been merged between when you started work on your branch +and when your pull request was approved, you will have to update your +branch. The preferred way to do so is with a rebase. + +Assuming you are on your working branch: + +.. code:: bash + + git pull origin master + git rebase master + +If you have changed files that were also changed in the intervening +merge, ``git rebase`` may report merge conflicts. If this happens, don’t +panic! Use ``git status`` and ``git diff`` to determine which files +conflict and where, use an editor to fix the conflicts, then stage the +formerly-conflicting files with ``git add FILE``. Finally, use +``git rebase --continue`` to apply the fix and continue rebasing. Note +that you may have to fix conflicts multiple times in a single rebase. + +It is also a good idea to replace the label ``Ready for Review`` with +``Ready for Re-Review`` for clarity. diff --git a/LICENSE.rst b/LICENSE.rst new file mode 100644 index 00000000..b2d9f640 --- /dev/null +++ b/LICENSE.rst @@ -0,0 +1,25 @@ +License +======= + +MIT License + +Copyright (c) 2018 UBC Launch Pad + +Permission is hereby granted, free of charge, to any person obtaining a +copy of this software and associated documentation files (the +“Software”), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/Pipfile b/Pipfile index 714b52c1..1e7ea6c2 100644 --- a/Pipfile +++ b/Pipfile @@ -26,7 +26,6 @@ watchtower = "==0.7.3" awscli = "*" codecov = "==2.1.7" flake8 = "*" -m2r = "*" ipython = "*" pycodestyle = "*" pylint = "*" diff --git a/docs/Config.md b/docs/Config.md deleted file mode 100644 index b229c03e..00000000 --- a/docs/Config.md +++ /dev/null @@ -1,117 +0,0 @@ -# The Configuration System - -We use environmental variables for all of our configuration-related things. A -sample `.env` file (which is what `pipenv` looks for when it tries to launch) -can be found at `sample-env`. Here is how each variable works. **Note: all -variables are strings**. - -For variables that require newlines (such as signing keys), replace the -newlines with `\n`. You can use the following command on most systems to -generate such a string: - -```bash -awk '{printf "%s\\n", $0}' $FILE -``` - -For JSON variables, you can just remove the newlines: - -```bash -awk '{printf "%s", $0}' $FILE -``` - -## SLACK\_SIGNING\_SECRET - -Signing secret of the slack app. Can be found in the basic information tab of -your slack app (api.slack.com/apps). - -## SLACK\_API\_TOKEN - -The Slack API token of your Slack bot. Can be found under OAuth & Permissions -tab of your slack app (under the name "Bot user OAuth access token"). - -The following permission scopes are required: - -- `channels:read` -- `channels:manage` -- `chats:write` -- `users.profile:read` -- `users:read` -- `commands` -- `groups:read` -- `im:write` - -You must also configure a slash command integration as well (under "Slash -commands") for the URL path `/slack/commands` of your Rocket instance. - -## SLACK\_NOFICIATION\_CHANNEL - -Name of the channel you want to have our rocket 2 slack bot to make -service notifications in. - -## SLACK\_ANNOUNCEMENT\_CHANNEL - -Name of the channel you want to have our rocket 2 slack bot to make -announcements in. - -## GITHUB\_APP\_ID - -The ID of your Github app (found under your Github organization settings -> -Developer Settings -> Github Apps -> Edit). - -## GITHUB\_ORG\_NAME - -The name of your Github organization (the string in the URL whenever you go to -the organization. - -## GITHUB\_WEBHOOK\_ENDPT - -The path GitHub posts webhooks to. Note that the following events must be -enabled (configured in GitHub app settings > "Permissions & events" > -"Subscribe to events"): - -- Membership -- Organization -- Team -- Team add - -When configuring webhooks, provide the URL path `/slack/commands` of your -Rocket instance. - -## GITHUB\_WEBHOOK\_SECRET - -A random string of characters you provide to Github to help further obfuscate -and verify that the webhook is indeed coming from Github. - -## GITHUB\_KEY - -The Github app signing key (can be found under Github organization settings -> -Developer Settings -> Github Apps -> Edit (at the bottom you generate and -download the key)). Paste the contents of the file as a string. See -[deployment](Deployment.html#github-key) for troubleshooting. - -The following permissions must be set to "Read & Write" for the associated -GitHub app (configured in GitHub app settings > "Permissions & events" > -"Organization permissions"): - -- Organization members - -## AWS\_ACCESS\_KEYID - -The AWS access key id. - -## AWS\_SECRET\_KEY - -The AWS secret key. - -## AWS\_\*\_TABLE - -The names of the various tables (leave these as they are). - -## AWS\_REGION - -The region where the AWS instance is located (leave these as they are). - -## AWS\_LOCAL - -Point all AWS DynamoDB requests to `http://localhost:8000`. Optional, and -defaults to `False`. diff --git a/docs/Config.rst b/docs/Config.rst new file mode 100644 index 00000000..6a58647b --- /dev/null +++ b/docs/Config.rst @@ -0,0 +1,135 @@ +The Configuration System +======================== + +We use environmental variables for all of our configuration-related +things. A sample ``.env`` file (which is what ``pipenv`` looks for when +it tries to launch) can be found at ``sample-env``. Here is how each +variable works. **Note: all variables are strings**. + +For variables that require newlines (such as signing keys), replace the +newlines with ``\n``. You can use the following command on most systems +to generate such a string: + +.. code:: bash + + awk '{printf "%s\\n", $0}' $FILE + +For JSON variables, you can just remove the newlines: + +.. code:: bash + + awk '{printf "%s", $0}' $FILE + +SLACK_SIGNING_SECRET +-------------------- + +Signing secret of the slack app. Can be found in the basic information +tab of your slack app (api.slack.com/apps). + +SLACK_API_TOKEN +--------------- + +The Slack API token of your Slack bot. Can be found under OAuth & +Permissions tab of your slack app (under the name “Bot user OAuth access +token”). + +The following permission scopes are required: + +- ``channels:read`` +- ``channels:manage`` +- ``chats:write`` +- ``users.profile:read`` +- ``users:read`` +- ``commands`` +- ``groups:read`` +- ``im:write`` + +You must also configure a slash command integration as well (under +“Slash commands”) for the URL path ``/slack/commands`` of your Rocket +instance. + +SLACK_NOFICIATION_CHANNEL +------------------------- + +Name of the channel you want to have our rocket 2 slack bot to make +service notifications in. + +SLACK_ANNOUNCEMENT_CHANNEL +-------------------------- + +Name of the channel you want to have our rocket 2 slack bot to make +announcements in. + +GITHUB_APP_ID +------------- + +The ID of your Github app (found under your Github organization settings +-> Developer Settings -> Github Apps -> Edit). + +GITHUB_ORG_NAME +--------------- + +The name of your Github organization (the string in the URL whenever you +go to the organization. + +GITHUB_WEBHOOK_ENDPT +-------------------- + +The path GitHub posts webhooks to. Note that the following events must +be enabled (configured in GitHub app settings > “Permissions & events” > +“Subscribe to events”): + +- Membership +- Organization +- Team +- Team add + +When configuring webhooks, provide the URL path ``/slack/commands`` of +your Rocket instance. + +GITHUB_WEBHOOK_SECRET +--------------------- + +A random string of characters you provide to Github to help further +obfuscate and verify that the webhook is indeed coming from Github. + +GITHUB_KEY +---------- + +The Github app signing key (can be found under Github organization +settings -> Developer Settings -> Github Apps -> Edit (at the bottom you +generate and download the key)). Paste the contents of the file as a +string. See `deployment `__ for +troubleshooting. + +The following permissions must be set to “Read & Write” for the +associated GitHub app (configured in GitHub app settings > “Permissions +& events” > “Organization permissions”): + +- Organization members + +AWS_ACCESS_KEYID +---------------- + +The AWS access key id. + +AWS_SECRET_KEY +-------------- + +The AWS secret key. + +AWS_*_TABLE +----------- + +The names of the various tables (leave these as they are). + +AWS_REGION +---------- + +The region where the AWS instance is located (leave these as they are). + +AWS_LOCAL +--------- + +Point all AWS DynamoDB requests to ``http://localhost:8000``. Optional, +and defaults to ``False``. diff --git a/docs/Database.md b/docs/Database.md deleted file mode 100644 index 58388e3a..00000000 --- a/docs/Database.md +++ /dev/null @@ -1,58 +0,0 @@ -# Database Reference - -## `users` Table - -The `users` table stores all the users. With DynamoDB, we only need to specify a -fixed attribute to be the primary index. In this case, the user's `slack_id` is -the primary index. All other attributes are specified in the `model/user.py` -file, and are also listed here: - -Attribute Name | Description ----|--- -`slack_id` | `String`; The user's slack id -`email` | `String`; The user's email address -`github` | `String`; The user's Github handler -`github_user_id` | `String`; The user's Github user ID -`major` | `String`; The subject major the user is in -`position` | `String`; The user's position in _Launch Pad_ -`bio` | `String`; A short (auto)biography -`image_url` | `String`; The user's avatar image URL -`permission_level` | `String`; The user's permission level -`karma` | `Integer`; The user's karma points - -The user's permission level is one of [`member`, `admin`, `team_lead`]. - -## `teams` Table - -The `teams` table stores all teams where `github_team_id` is the primary index. -All other attributes are specified in the `model/team.py` file, and are also -listed here: - -Attribute Name | Description ----|--- -`github_team_id` | `String`; The team's Github ID -`github_team_name` | `String`; The team's Github name -`display_name` | `String`; The teams's display -`platform` | `String`; The team's working platform -`team_leads` | `String Set`; The team's set of team leads' Github IDs -`members` | `String Set`; The team's set of members' Github IDs - -## `projects` Table - -The `projects` table stores all projects where `project_id` is the primary -index. All other attributes are specified in the `model/project.py` file, and -are also listed here: - -Attribute Name | Description ----|--- -`project_id` | `String`; The project's unique SHA1 ID, salted with a timestamp -`github_team_id` | `String`; The team's Github ID associated with the project -`github_urls` | `String Set`; A set of URLs pointing to project repositories -`display_name` | `String`; A name for the project -`short_description` | `String`; A short description that outlines the project -`long_description` | `String`; A longer and more in-depth description -`tags` | `String Set`; A set of tags taken from the Github repositories -`website_url` | `String`; A URL to the project's website -`medium_url` | `String`; A URL to the project's medium page -`appstore_url` | `String`; A URL to the project's Apple Appstore page -`playstore_url` | `String`; A URL to the project's Google Playstore page diff --git a/docs/Database.rst b/docs/Database.rst new file mode 100644 index 00000000..42d3376a --- /dev/null +++ b/docs/Database.rst @@ -0,0 +1,95 @@ +Database Reference +================== + +``users`` Table +--------------- + +The ``users`` table stores all the users. With DynamoDB, we only need to +specify a fixed attribute to be the primary index. In this case, the +user’s ``slack_id`` is the primary index. All other attributes are +specified in the ``model/user.py`` file, and are also listed here: + +==================== =============================================== +Attribute Name Description +==================== =============================================== +``slack_id`` ``String``; The user’s slack id +``email`` ``String``; The user’s email address +``github`` ``String``; The user’s Github handler +``github_user_id`` ``String``; The user’s Github user ID +``major`` ``String``; The subject major the user is in +``position`` ``String``; The user’s position in *Launch Pad* +``bio`` ``String``; A short (auto)biography +``image_url`` ``String``; The user’s avatar image URL +``permission_level`` ``String``; The user’s permission level +``karma`` ``Integer``; The user’s karma points +==================== =============================================== + +The user’s permission level is one of [``member``, ``admin``, +``team_lead``]. + +``teams`` Table +--------------- + +The ``teams`` table stores all teams where ``github_team_id`` is the +primary index. All other attributes are specified in the +``model/team.py`` file, and are also listed here: + ++----------------------+----------------------------------------------+ +| Attribute Name | Description | ++======================+==============================================+ +| ``github_team_id`` | ``String``; The team’s Github ID | ++----------------------+----------------------------------------------+ +| ``github_team_name`` | ``String``; The team’s Github name | ++----------------------+----------------------------------------------+ +| ``display_name`` | ``String``; The teams’s display | ++----------------------+----------------------------------------------+ +| ``platform`` | ``String``; The team’s working platform | ++----------------------+----------------------------------------------+ +| ``team_leads`` | ``String Set``; The team’s set of team | +| | leads’ Github IDs | ++----------------------+----------------------------------------------+ +| ``members`` | ``String Set``; The team’s set of members’ | +| | Github IDs | ++----------------------+----------------------------------------------+ + +``projects`` Table +------------------ + +The ``projects`` table stores all projects where ``project_id`` is the +primary index. All other attributes are specified in the +``model/project.py`` file, and are also listed here: + ++-----------------------+---------------------------------------------+ +| Attribute Name | Description | ++=======================+=============================================+ +| ``project_id`` | ``String``; The project’s unique SHA1 ID, | +| | salted with a timestamp | ++-----------------------+---------------------------------------------+ +| ``github_team_id`` | ``String``; The team’s Github ID associated | +| | with the project | ++-----------------------+---------------------------------------------+ +| ``github_urls`` | ``String Set``; A set of URLs pointing to | +| | project repositories | ++-----------------------+---------------------------------------------+ +| ``display_name`` | ``String``; A name for the project | ++-----------------------+---------------------------------------------+ +| ``short_description`` | ``String``; A short description that | +| | outlines the project | ++-----------------------+---------------------------------------------+ +| ``long_description`` | ``String``; A longer and more in-depth | +| | description | ++-----------------------+---------------------------------------------+ +| ``tags`` | ``String Set``; A set of tags taken from | +| | the Github repositories | ++-----------------------+---------------------------------------------+ +| ``website_url`` | ``String``; A URL to the project’s website | ++-----------------------+---------------------------------------------+ +| ``medium_url`` | ``String``; A URL to the project’s medium | +| | page | ++-----------------------+---------------------------------------------+ +| ``appstore_url`` | ``String``; A URL to the project’s Apple | +| | Appstore page | ++-----------------------+---------------------------------------------+ +| ``playstore_url`` | ``String``; A URL to the project’s Google | +| | Playstore page | ++-----------------------+---------------------------------------------+ diff --git a/docs/Deployment.md b/docs/Deployment.md deleted file mode 100644 index d7ccfc9f..00000000 --- a/docs/Deployment.md +++ /dev/null @@ -1,135 +0,0 @@ -# Deployment - -## Deployment Process - -The following should be read as more of a reference than a guide. To deploy -Rocket 2, you must follow the steps as if you were building it for local use, -except some tweaks in regards to where it goes and more tooling-specific details -mentioned below. - -### Hosting - -Rocket 2 is currently hosted by an AWS EC2 t2.micro instance. Since this is a -single-threaded application with a single worker thread, there is not much of a -reason to go for anything more. **Note: Adding more worker threads may cause -"minor" issues such as the scheduler running more than once, weird exceptions, -and may prevent the server from running in some cases, which is why increasing -the number of worker threads beyond 1 is not recommended.** - -If need-be, Inertia can [help provision an instance for you][inert]. - -Should you wish to set up your own Rocket 2 instance for deployment, you should -first be able to set up a Rocket 2 instance for testing on a local computer -with `ngrok` forwarding. If you have successfully set up an instance on a remote -computer, you may still want to have a look. - -For those of you who don't want too much of a hassle, hosting via Heroku is also -a valid option, as Heroku does continuous deployment without the need of setting -up Inertia, and also has built-in SSL so you don't need to set anything up. Be -wary, however, that Heroku is almost twice as expensive as an AWS EC2 t2.micro -instance. - -Do note that you must set the environmental variables in the provided settings -page if you are to host via Heroku. For details regarding how you would input -the `GITHUB_KEY`, please see [below](#github-key). - -[inert]: https://inertia.ubclaunchpad.com/#provisioning-a-remote - -### SSL - -Before deploying for the first time, you must set up SSL and configuration for -Nginx, which we are using as a proxy server. This can be done by running the -`scripts/setup_deploy.sh` script. This runs the official -[Let's Encrypt](https://letsencrypt.org/) container to request SSL certificates, -sets up a cronjob to periodically re-validate them, and copies -`nginx.conf` to the correct location. Do note that the Let's -Encrypt container needs to use port 443, so if you have another process or -container using that port, you will need to kill it before running the -set up script. - -### Inertia - -For UBC Launch Pad, we continuously deploy off the `ec2-release` branch on -Github using UBC Launch Pad's -[Inertia](https://github.com/ubclaunchpad/inertia). This will pull the repo when -changes are merged, rebuild the containers from `docker-compose.yml`, and -redeploy. - -When deploying with Inertia, make sure that you are using a stable version of -Inertia. - -Since we have changed from using `.toml` configuration files to using -environmental variables for configuration, you must inject them using `inertia -{some name} env set AWS_LOCAL False` and the like. If you already have all your -environmental variables set up in your `.env` file, you can send the entire file -over with `inertia {some name} send .env`. - -#### GITHUB_KEY - -The `GITHUB_KEY` is merely the GPG private key used to sign Github API requests. -We simply shove the entire file into a string and use it in the environmental -variable. Do note that doing this on the command line is somewhat difficult -because `inertia` would treat the dashes `--` in the string as flags and get -confused. Another thing to watch out for is that the command line ignores the -new lines in the string. The current working method of doing this is to pass in -the entire string with a single quote (which means that every symbol is taken -literally), then for every dash in the string, we add a forward slash `\` in -front. We then replace all new lines with the literal `\n`. - -Our configuration code replaces these instances of `\-` and `\n` with actual -dashes and new lines. - -Note that these replacements are not necessary on Heroku and you can simply copy -and paste the contents of the key file directly into the box provided. - -If you are using the `.env` file approach, you only need to replace the new -lines and not the dashes. - -### Docker Compose - -Our main deployment configuration is contained in -`docker-compose.yml`. We deploy an Nginx container -to serve as a proxy, as well as building and running a Rocket 2 container. -The Nginx proxy exposes ports 80 and 443, for HTTP/S, which must also be -accessible from the outside world. The Rocket 2 container exposes port 5000, -as Gunicorn is listening on this port; this should *not* be accessible to -the outside world. - -Note that Docker Compose has a rather complex networking utility. In particular, -note that to access HTTP endpoints in other composed containers, you must -reference them by their service name in `docker-compose.yml`, *not* via -localhost. This is already handled in `nginx.conf`. - -## Other Build Tools - -### Github Actions CI - -[Github Actions CI](https://github.com/features/actions) is a continuous -integration service that is used to build and test software projects hosted on -Github. To configure Github CI, a file `pythonpackage.yml` needs to be added -to `.github/workflows/`. This YAML file will contain the commands for -the automated tests that needs to run. - -Every time a branch gets pushed into github, Github CI starts a job. A job is -where Github clones the GitHub repository into a new virtual environment to -test the code. - -### Docker - -[Docker](https://docs.docker.com/get-started/) is a program that run software -packages called containers. Every container is isolated from each other and is -a bundle (also known as image) of their own tools, applications, libraries and -configuration files. However, containers are able to also communicate with each -other through channels, and all containers are run by a single OS kernel. -We use Docker in Rocket2 to make deployment to the server easier. - -Docker is composed of 3 parts: Container, Services, and Stack. -`Dockerfile` defines the container. Inside `Dockerfile` is the environment that -would be set up. Inside the container for Rocket2, we have a copy of our app, -and all the dependencies and the virtual environment installed. - -`docker-compose.yml` defines the services that allow multiple containers to run -together. - -Docker is different than virtual machines because it can run multiple containers -using only one kernel which makes it more lightweight. diff --git a/docs/Deployment.rst b/docs/Deployment.rst new file mode 100644 index 00000000..15f602ac --- /dev/null +++ b/docs/Deployment.rst @@ -0,0 +1,152 @@ +Deployment +========== + +Deployment Process +------------------ + +The following should be read as more of a reference than a guide. To +deploy Rocket 2, you must follow the steps as if you were building it +for local use, except some tweaks in regards to where it goes and more +tooling-specific details mentioned below. + +Hosting +~~~~~~~ + +Rocket 2 is currently hosted by an AWS EC2 t2.micro instance. Since this +is a single-threaded application with a single worker thread, there is +not much of a reason to go for anything more. **Note: Adding more worker +threads may cause “minor” issues such as the scheduler running more than +once, weird exceptions, and may prevent the server from running in some +cases, which is why increasing the number of worker threads beyond 1 is +not recommended.** + +If need-be, Inertia can `help provision an instance for +you `__. + +Should you wish to set up your own Rocket 2 instance for deployment, you +should first be able to set up a Rocket 2 instance for testing on a +local computer with ``ngrok`` forwarding. If you have successfully set +up an instance on a remote computer, you may still want to have a look. + +For those of you who don’t want too much of a hassle, hosting via Heroku +is also a valid option, as Heroku does continuous deployment without the +need of setting up Inertia, and also has built-in SSL so you don’t need +to set anything up. Be wary, however, that Heroku is almost twice as +expensive as an AWS EC2 t2.micro instance. + +Do note that you must set the environmental variables in the provided +settings page if you are to host via Heroku. For details regarding how +you would input the ``GITHUB_KEY``, please see `below <#github-key>`__. + +SSL +~~~ + +Before deploying for the first time, you must set up SSL and +configuration for Nginx, which we are using as a proxy server. This can +be done by running the ``scripts/setup_deploy.sh`` script. This runs the +official `Let’s Encrypt `__ container to +request SSL certificates, sets up a cronjob to periodically re-validate +them, and copies ``nginx.conf`` to the correct location. Do note that +the Let’s Encrypt container needs to use port 443, so if you have +another process or container using that port, you will need to kill it +before running the set up script. + +Inertia +~~~~~~~ + +For UBC Launch Pad, we continuously deploy off the ``ec2-release`` +branch on Github using UBC Launch Pad’s +`Inertia `__. This will pull +the repo when changes are merged, rebuild the containers from +``docker-compose.yml``, and redeploy. + +When deploying with Inertia, make sure that you are using a stable +version of Inertia. + +Since we have changed from using ``.toml`` configuration files to using +environmental variables for configuration, you must inject them using +``inertia {some name} env set AWS_LOCAL False`` and the like. If you +already have all your environmental variables set up in your ``.env`` +file, you can send the entire file over with +``inertia {some name} send .env``. + +GITHUB_KEY +^^^^^^^^^^ + +The ``GITHUB_KEY`` is merely the GPG private key used to sign Github API +requests. We simply shove the entire file into a string and use it in +the environmental variable. Do note that doing this on the command line +is somewhat difficult because ``inertia`` would treat the dashes ``--`` +in the string as flags and get confused. Another thing to watch out for +is that the command line ignores the new lines in the string. The +current working method of doing this is to pass in the entire string +with a single quote (which means that every symbol is taken literally), +then for every dash in the string, we add a forward slash ``\`` in +front. We then replace all new lines with the literal ``\n``. + +Our configuration code replaces these instances of ``\-`` and ``\n`` +with actual dashes and new lines. + +Note that these replacements are not necessary on Heroku and you can +simply copy and paste the contents of the key file directly into the box +provided. + +If you are using the ``.env`` file approach, you only need to replace +the new lines and not the dashes. + +Docker Compose +~~~~~~~~~~~~~~ + +Our main deployment configuration is contained in +``docker-compose.yml``. We deploy an Nginx container to serve as a +proxy, as well as building and running a Rocket 2 container. The Nginx +proxy exposes ports 80 and 443, for HTTP/S, which must also be +accessible from the outside world. The Rocket 2 container exposes port +5000, as Gunicorn is listening on this port; this should *not* be +accessible to the outside world. + +Note that Docker Compose has a rather complex networking utility. In +particular, note that to access HTTP endpoints in other composed +containers, you must reference them by their service name in +``docker-compose.yml``, *not* via localhost. This is already handled in +``nginx.conf``. + +Other Build Tools +----------------- + +Github Actions CI +~~~~~~~~~~~~~~~~~ + +`Github Actions CI `__ is a +continuous integration service that is used to build and test software +projects hosted on Github. To configure Github CI, a file +``pythonpackage.yml`` needs to be added to ``.github/workflows/``. This +YAML file will contain the commands for the automated tests that needs +to run. + +Every time a branch gets pushed into github, Github CI starts a job. A +job is where Github clones the GitHub repository into a new virtual +environment to test the code. + +Docker +~~~~~~ + +`Docker `__ is a program that run +software packages called containers. Every container is isolated from +each other and is a bundle (also known as image) of their own tools, +applications, libraries and configuration files. However, containers are +able to also communicate with each other through channels, and all +containers are run by a single OS kernel. We use Docker in Rocket2 to +make deployment to the server easier. + +Docker is composed of 3 parts: Container, Services, and Stack. +``Dockerfile`` defines the container. Inside ``Dockerfile`` is the +environment that would be set up. Inside the container for Rocket2, we +have a copy of our app, and all the dependencies and the virtual +environment installed. + +``docker-compose.yml`` defines the services that allow multiple +containers to run together. + +Docker is different than virtual machines because it can run multiple +containers using only one kernel which makes it more lightweight. diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md deleted file mode 100644 index ff31fdc3..00000000 --- a/docs/GettingStarted.md +++ /dev/null @@ -1,75 +0,0 @@ -# Getting Started - -## Create an User Model for DynamoDB database - -A quick guide run through how Rocket2 takes in a command to generate a model -that will be stored onto the database. - -So you just joined Launchpad and want to add yourself to Rocket2. You go on -slack and starts to talk to the Rocket2 bot, but what should you say? -To get started, here's a command you can enter: - -### command - -A slack user calls Rocket2 to edit their information. - -```sh -# SLACK_ID will be the current user's slack id. -# For this example, let's assume the slack id to be `StevenU` -/rocket user edit --name "Steven Universe" --email "su@gmail.com" -``` - -Yay! You have done what you were told to do, but wait! As a curious software -developer, you're curious about what makes Rocket2 tick. How exactly is your -information saved onto Rocket2? Well, for every member added to Rocket2, a user -model gets created. - -### model - -An User model is constructed from the information the user input. Unfilled -parameters will remain empty. - -```python -# To construct a User model with Slack ID 'StevenU' -steven_universe = User('StevenU') -steven_universe.email = 'su@gmail.com' - -# To check if this user is valid. -User.is_valid(steven_universe) # returns true - -# To get a user's permission level. -steven_universe.permissions_level # returns Permissions_member -``` - -Launchpad is growing every year, so there are a lot of user, hence a lot of user -models. We have to be able to keep track and organize everyone, so that's where -database comes in. We create a table for every type of model, so in this case -we'll create a user table to store all users. - -### database (db) - -Instead of using `dynamodb.py` to handle our User model, we will use `facade.py` -so we avoid becoming dependent on a single database. In the future, this allows -us to easily switch to using other databases. - -```python -# To store an user into the database. -facade.store(steven_universe) - -# To retrieve an user from the database. -facade.retrieve(User, 'StevenU') # returns steven_universe user model - -# If we try to retrieve a non-existent: user, a LookupError will be thrown. -facade.retrieve(User, 'fakeU') # returns 'User fakeU not found' - -# To query an user based on a parameter, a list of matching Users will be -returned. -facade.query(User, ['name', 'Steven Universe'] # returns [steven_universe] - -# To query an user based on a non-existent parameter, an empty list will be -returned. -facade.query(User, ['email', 'fakeemail@gmail.com'] # returns [] - -# To query an user without parameters, all the users will be returned -facade.query(User, []) # returns [steven_universe, second_user] -``` diff --git a/docs/GettingStarted.rst b/docs/GettingStarted.rst new file mode 100644 index 00000000..bc4c7078 --- /dev/null +++ b/docs/GettingStarted.rst @@ -0,0 +1,80 @@ +Getting Started +=============== + +Create an User Model for DynamoDB database +------------------------------------------ + +A quick guide run through how Rocket2 takes in a command to generate a +model that will be stored onto the database. + +So you just joined Launchpad and want to add yourself to Rocket2. You go +on slack and starts to talk to the Rocket2 bot, but what should you say? +To get started, here’s a command you can enter: + +command +~~~~~~~ + +A slack user calls Rocket2 to edit their information. + +.. code:: sh + + # SLACK_ID will be the current user's slack id. + # For this example, let's assume the slack id to be `StevenU` + /rocket user edit --name "Steven Universe" --email "su@gmail.com" + +Yay! You have done what you were told to do, but wait! As a curious +software developer, you’re curious about what makes Rocket2 tick. How +exactly is your information saved onto Rocket2? Well, for every member +added to Rocket2, a user model gets created. + +model +~~~~~ + +An User model is constructed from the information the user input. +Unfilled parameters will remain empty. + +.. code:: python + + # To construct a User model with Slack ID 'StevenU' + steven_universe = User('StevenU') + steven_universe.email = 'su@gmail.com' + + # To check if this user is valid. + User.is_valid(steven_universe) # returns true + + # To get a user's permission level. + steven_universe.permissions_level # returns Permissions_member + +Launchpad is growing every year, so there are a lot of user, hence a lot +of user models. We have to be able to keep track and organize everyone, +so that’s where database comes in. We create a table for every type of +model, so in this case we’ll create a user table to store all users. + +database (db) +~~~~~~~~~~~~~ + +Instead of using ``dynamodb.py`` to handle our User model, we will use +``facade.py`` so we avoid becoming dependent on a single database. In +the future, this allows us to easily switch to using other databases. + +.. code:: python + + # To store an user into the database. + facade.store(steven_universe) + + # To retrieve an user from the database. + facade.retrieve(User, 'StevenU') # returns steven_universe user model + + # If we try to retrieve a non-existent: user, a LookupError will be thrown. + facade.retrieve(User, 'fakeU') # returns 'User fakeU not found' + + # To query an user based on a parameter, a list of matching Users will be + returned. + facade.query(User, ['name', 'Steven Universe'] # returns [steven_universe] + + # To query an user based on a non-existent parameter, an empty list will be + returned. + facade.query(User, ['email', 'fakeemail@gmail.com'] # returns [] + + # To query an user without parameters, all the users will be returned + facade.query(User, []) # returns [steven_universe, second_user] diff --git a/docs/KarmaCommands.md b/docs/KarmaCommands.md deleted file mode 100644 index 1d9bf805..00000000 --- a/docs/KarmaCommands.md +++ /dev/null @@ -1,53 +0,0 @@ -# Karma Command Reference - -Command to giveth or taketh away a user's karma - -## Options - -### For normal users - -#### Add 1 karma to user - -```sh -/rocket @user ++ -``` - -#### View a user's karma - -```sh -/rocket karma view @user -``` - -### For admin only - -#### Set user karma - -```sh -/rocket karma set @user {amount} -``` - -#### Reset all user karma - -```sh -/rocket karma reset --all -``` - -### Examples - -```sh -# normal user -/rocket @coolkid1 ++ #adds 1 karma to coolkid1 -/rocket karma view @coolkid1 #view how much karma coolkid1 has - -# admin only -/rocket karma set @coolkid1 5 #sets coolkid's karma to 5 -/rocket karma reset --all #resets all users karma to 1 -``` - -#### Help - -##### Display options for karma commands - -```sh -/rocket karma help -``` diff --git a/docs/KarmaCommands.rst b/docs/KarmaCommands.rst new file mode 100644 index 00000000..e18d69d2 --- /dev/null +++ b/docs/KarmaCommands.rst @@ -0,0 +1,64 @@ +Karma Command Reference +======================= + +Command to giveth or taketh away a user’s karma + +Options +------- + +For normal users +~~~~~~~~~~~~~~~~ + +Add 1 karma to user +^^^^^^^^^^^^^^^^^^^ + +.. code:: sh + + /rocket @user ++ + +View a user’s karma +^^^^^^^^^^^^^^^^^^^ + +.. code:: sh + + /rocket karma view @user + +For admin only +~~~~~~~~~~~~~~ + +Set user karma +^^^^^^^^^^^^^^ + +.. code:: sh + + /rocket karma set @user {amount} + +Reset all user karma +^^^^^^^^^^^^^^^^^^^^ + +.. code:: sh + + /rocket karma reset --all + +Examples +~~~~~~~~ + +.. code:: sh + + # normal user + /rocket @coolkid1 ++ #adds 1 karma to coolkid1 + /rocket karma view @coolkid1 #view how much karma coolkid1 has + + # admin only + /rocket karma set @coolkid1 5 #sets coolkid's karma to 5 + /rocket karma reset --all #resets all users karma to 1 + +Help +^^^^ + +Display options for karma commands +'''''''''''''''''''''''''''''''''' + +.. code:: sh + + /rocket karma help diff --git a/docs/LocalDevelopmentGuide.md b/docs/LocalDevelopmentGuide.md deleted file mode 100644 index e6719f44..00000000 --- a/docs/LocalDevelopmentGuide.md +++ /dev/null @@ -1,274 +0,0 @@ -# Local Development Guide - -So, you want to see some progress, preferably on Slack, and not just in the -forms of unit testing? At this point, fear is actually a reasonable response. -With this guide, you can be talking to your locally-hosted Slack bot in no time! - -> **Warning**: This only works smoothly with a Unix machine (macOS or Linux -> variants). Windows users may be in for more pain than expected. - -## 1: Set up a HTTPS Tunnel - -Slack requires that all webhooks are passed through HTTPS. This is rather -inconvenient if you just want to test while running on your local computer. -There are several ways to get around this. - -### Ngrok - -Ngrok is a forwarding service that hosts a public HTTPS URL that -passes to your local computer. Sign up for ngrok and download it -[here][download-ngrok]. - -After installing, run `ngrok http 5000` to create an ngrok URL that will be -passed to your local port 5000. As long as you run Rocket on port 5000 (see -below), you can then access it through the HTTPS URL that ngrok gives you. Note -that it is very important to use the HTTPS URL, *not* the HTTP URL. - -### Localtunnel - -An alternative to Ngrok is [localtunnel](https://GitHub.com/localtunnel/localtunnel), -which works similarly to Ngrok but allows you to use the same domain every -time. For example: - -```bash -$ lt --port 5000 --subdomain my-amazing-rocket2 -your url is: https://my-amazing-rocket2.loca.lt -``` - -## 2: Create a Slack Workspace - -For testing, it's useful to have your own Slack workspace set up. If you do not -already have one, go [here][create-workspace] to create one, and follow the -steps to set it up. - -## 3: Create a Slack App - -Follow the link [here][make-slack-app] to create a new Slack app - you can name -it whatever you like - and install it to the appropriate workspace. - -### 3.1: Add a Bot Token - -In "OAuth and Permissions", select the Bot Token Scopes described in -[the Slack configuration docs](slack-configuration). - -### 3.2: Install Slack App - -In "Install your app to your workspace," click the button to install to your -workspace. This will take you to a permissions page for the workspace - make -sure this is for the correct workspace, and allow the app to connect. - -Once this is done, you will be provided with an API token. - -### 3.3: Determine Credentials - -Make note of the app's signing secret, found in Settings -> Basic Information -> -App Credentials, and the bot user OAuth access token, found in Features -> -OAuth & Permissions -> Tokens for Your Workspace. These will be needed for the -configuration step later. - -## 4: Gain Access to AWS - -Rocket makes use of AWS DynamoDB as its database. There is also an optional -logging component that leverages AWS CloudWatch. - -### Using Real AWS - -If you do not already have access to DynamoDB and CloudWatch, you can use it as -part of the free tier of AWS. Create an AWS account for yourself, then go to -the IAM service and create a new user. The user name doesn't particularly -matter (though `rocket2-dev-$NAME` is recommended), but make sure you check -"programmatic access." In permissions, go to "Attach existing permissions -directly" and add the following policies: - -- `AmazonDynamoDBFullAccess` -- `CloudWatchLogsFullAccess` - -As you may have noticed, we not only want to use DynamoDB, but also CloudWatch. -We send our logs to CloudWatch for easier storage and querying. - -Finally, copy the provided access key ID and secret access key after creating -the new user. - -Note: if you are in the `brussel-sprouts` GitHub team, you should already have -AWS credentials. Just ask. - -### Using Local AWS - -Alternatively, just set up [DynamoDB locally][localdynamodb] (the Docker-based -setup is probably the easiest) and set `AWS_LOCAL=True`. - -CloudWatch integration is not currently supported in this manner. - -### 5: Set up a GitHub App and organization - -Create a Rocket 2 Github under an appropriate testing organization. Make sure -to install the GitHub App to the organization in addition to registering it. -All this can be done from a GitHub organization's Settings > GitHub Apps page. - -In the GitHub app's settings, go to "Private keys" and click "Generate a new -private key". This will generate and allow you to download a new secret key for -Rocket 2. Save this to the `credentials/` directory as `gh_signing_key.pem` - -it should already be in the PEM file format, bracketed by: - -``` ------BEGIN RSA PRIVATE KEY----- -... ------END RSA PRIVATE KEY----- -``` - -Authenticating Rocket 2 as a GitHub App and obtaining an access token for the -GitHub API should be automated, once the signing key is available. Refer to -the [GitHub key configuration docs](Config.md#github-key) for the required -permissions. - -After doing this, remember to put your tunneled HTTPS URL with `/webhook` -appended at the end into the "Webhook URL" box. Refer to the -[GitHub webhook configuration docs](Config.md#github-webhook-endpt) for the -required subscriptions. - -## 6: Set Up Configuration - -Our repo already contains `sample-env`, the main environmental configuration -file for the entire app, as well as the `credentials/` directory, where you -will put credential files like the GitHub app private key. - -Please [read the configuration docs][config] for more details. - -## 7: Build and Run Rocket 2 - -This section assumes you already have installed Docker. Assuming you are in the -directory containing the Dockerfile, all you need to do to build and run is the -following two commands (run from the root of your project directory): - -```bash -scripts/docker_build.sh -scripts/docker_run_local.sh --env-file .env -``` - -Optionally, for [local DynamoDB](#using-local-aws): - -```bash -scripts/docker_run_local.sh --env-file .env --network="host" -``` - -The option [`--env-file`][docker-env-file] -lets you pass in your [configuration options][config]. - -For the curious, you can take a look at the contents of the referenced scripts -above. Note that the options passed to `-p` in `docker run` tell Docker what -port to run Rocket on. `0.0.0.0` is the IP address (in this case, localhost), -the first `5000` is the port exposed inside the container, and the second -`5000` is the port exposed outside the container. The port exposed outside -the container can be changed (for instance, if port 5000 is already -in use in your local development environment), but in that case ensure that -your tunnel is running on the same port. - -### 6.1: [Optional] Running without Docker - -We highly recommend building and running on Docker, but building every time -you make a tiny change can be inconvenient. If you would like to run without -building a new Docker image every time, you can do so with `pipenv run launch`. -This is in fact the same command Docker runs, but if you run outside Docker, -you may run into errors due to unexpected changes in your local development -environment. - -## 7: Configure Slack App Features - -In addition to a bot user, there are a couple other features that need to be -enabled in the Slack app once the local instance of Rocket is running. - -### 7.1: Add Event Subscriptions - -In "Add features and functionality", add event subscriptions. In particular, -under Request URL, submit the ngrok HTTPS URL with `/slack/events` appended to -the end. Note that ngrok will generate a new HTTPS URL every time it runs, so -you will have to repeat this step every time you launch ngrok. You will then -have to enable workspace and/or bot events that we want Rocket to listen for, -like the `team_join` workspace event - ask the team for the most up-to-date list -of these. - -### 7.2: Add Slash Command - -In "Add features and functionality", add a slash command. In particular, under -Request URL, submit the ngrok HTTPS URL with `/slack/commands` appended to the -end. For the actual command, anything will work, though the final app will use -`/rocket`. Make sure you tick the box marked "Escape channels, users, and links -sent to your app", or else none of the @ signs will work properly! - -## 8: Testing - -This is the final and most important part: testing if it actually works or not. -Go to your Slack workspace and add Rocket (or whatever you named your Slack bot) -to the channel if you have yet to do so (just type `@` and Slack will -ask if you want to invite the bot into the channel). - -To test if Rocket is running, type the command: - -``` -/rocket user help -``` - -If you see a list of options, Rocket is working! - -### 8.1: Setting Up Admin Permissions - -We currently haven't finished the command to add a user to the database or -make them an admin, so we have to do it manually. - -First, determine your Slack ID by reading the logs. The logs are formatted like -so: - -``` -{slackid_making_the_command}:{command_itself} -``` - -The Slack IDs of other users will appear when you type `@` followed by whatever -the user's handle is. Slack automatically converts that handle into an ID. - -Then, you have an option of either using the AWS command-line interface or -using the AWS web interface. - -You should already have the command line interface installed via pipenv. If not, -run the command `pipenv install --dev`. Note that to run commands, you will -either have to go into the pipenv environment (with `pipenv shell`) or prefix -every command with `pipenv run`. Here is the command to create a user with a: - -```bash -# The following command is split into multiple lines because it is long. Make -# sure that the actal command isn't split into multiple lines because it may -# complicate things. -aws dynamodb put-item --table-name USERS_TABLE\ - --item '{"slack_id":{"S": "UE7PAG75L"}, - "permission_level":{"S": "admin"}}'\ - --endpoint-url http://localhost:8000 -``` - -Replace `USERS_TABLE` with whatever name you set in `config.toml`. - -Alternatively, you can directly edit the DynamoDB table via the AWS web -interface. Go to the DynamoDB service in the AWS web interface and open -the appropriate table. Click on the Items tab and then on "Create item". -Make sure there's a column for `slack_id` and `permission_level`, -where `slack_id` is a `String` with the appropriate value and -`permission_level` is a `String` with the value `admin`. - -### 8.2: Viewing a User - -``` -/rocket user view -``` - -The output of this command should be a stylish table displaying your Slack id -and permissions level. - -Now, you can continue with whatever testing you originally wanted to do. -Remember to rebulid your Docker image every time you make a change! - -[config]: Config.html -[create-workspace]: https://slack.com/create -[make-slack-app]: https://api.slack.com/apps -[slack-configuration]: Config.html#slack-api-token -[download-ngrok]: https://ngrok.com/ -[GitHub-token]: https://GitHub.com/settings/tokens -[docker-env-file]: https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file -[localdynamodb]: index.html#running-dynamodb-locally diff --git a/docs/LocalDevelopmentGuide.rst b/docs/LocalDevelopmentGuide.rst new file mode 100644 index 00000000..f0877feb --- /dev/null +++ b/docs/LocalDevelopmentGuide.rst @@ -0,0 +1,307 @@ +Local Development Guide +======================= + +So, you want to see some progress, preferably on Slack, and not just in +the forms of unit testing? At this point, fear is actually a reasonable +response. With this guide, you can be talking to your locally-hosted +Slack bot in no time! + + **Warning**: This only works smoothly with a Unix machine (macOS or + Linux variants). Windows users may be in for more pain than expected. + +1: Set up a HTTPS Tunnel +------------------------ + +Slack requires that all webhooks are passed through HTTPS. This is +rather inconvenient if you just want to test while running on your local +computer. There are several ways to get around this. + +Ngrok +~~~~~ + +Ngrok is a forwarding service that hosts a public HTTPS URL that passes +to your local computer. Sign up for ngrok and download it +`here `__. + +After installing, run ``ngrok http 5000`` to create an ngrok URL that +will be passed to your local port 5000. As long as you run Rocket on +port 5000 (see below), you can then access it through the HTTPS URL that +ngrok gives you. Note that it is very important to use the HTTPS URL, +*not* the HTTP URL. + +Localtunnel +~~~~~~~~~~~ + +An alternative to Ngrok is +`localtunnel `__, which +works similarly to Ngrok but allows you to use the same domain every +time. For example: + +.. code:: bash + + $ lt --port 5000 --subdomain my-amazing-rocket2 + your url is: https://my-amazing-rocket2.loca.lt + +2: Create a Slack Workspace +--------------------------- + +For testing, it’s useful to have your own Slack workspace set up. If you +do not already have one, go `here `__ to +create one, and follow the steps to set it up. + +3: Create a Slack App +--------------------- + +Follow the link `here `__ to create a new +Slack app - you can name it whatever you like - and install it to the +appropriate workspace. + +3.1: Add a Bot Token +~~~~~~~~~~~~~~~~~~~~ + +In “OAuth and Permissions”, select the Bot Token Scopes described in +`the Slack configuration docs `__. + +3.2: Install Slack App +~~~~~~~~~~~~~~~~~~~~~~ + +In “Install your app to your workspace,” click the button to install to +your workspace. This will take you to a permissions page for the +workspace - make sure this is for the correct workspace, and allow the +app to connect. + +Once this is done, you will be provided with an API token. + +3.3: Determine Credentials +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Make note of the app’s signing secret, found in Settings -> Basic +Information -> App Credentials, and the bot user OAuth access token, +found in Features -> OAuth & Permissions -> Tokens for Your Workspace. +These will be needed for the configuration step later. + +4: Gain Access to AWS +--------------------- + +Rocket makes use of AWS DynamoDB as its database. There is also an +optional logging component that leverages AWS CloudWatch. + +Using Real AWS +~~~~~~~~~~~~~~ + +If you do not already have access to DynamoDB and CloudWatch, you can +use it as part of the free tier of AWS. Create an AWS account for +yourself, then go to the IAM service and create a new user. The user +name doesn’t particularly matter (though ``rocket2-dev-$NAME`` is +recommended), but make sure you check “programmatic access.” In +permissions, go to “Attach existing permissions directly” and add the +following policies: + +- ``AmazonDynamoDBFullAccess`` +- ``CloudWatchLogsFullAccess`` + +As you may have noticed, we not only want to use DynamoDB, but also +CloudWatch. We send our logs to CloudWatch for easier storage and +querying. + +Finally, copy the provided access key ID and secret access key after +creating the new user. + +Note: if you are in the ``brussel-sprouts`` GitHub team, you should +already have AWS credentials. Just ask. + +Using Local AWS +~~~~~~~~~~~~~~~ + +Alternatively, just set up `DynamoDB +locally `__ (the Docker-based setup +is probably the easiest) and set ``AWS_LOCAL=True``. + +CloudWatch integration is not currently supported in this manner. + +5: Set up a GitHub App and organization +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create a Rocket 2 Github under an appropriate testing organization. Make +sure to install the GitHub App to the organization in addition to +registering it. All this can be done from a GitHub organization’s +Settings > GitHub Apps page. + +In the GitHub app’s settings, go to “Private keys” and click “Generate a +new private key”. This will generate and allow you to download a new +secret key for Rocket 2. Save this to the ``credentials/`` directory as +``gh_signing_key.pem`` - it should already be in the PEM file format, +bracketed by: + +:: + + -----BEGIN RSA PRIVATE KEY----- + ... + -----END RSA PRIVATE KEY----- + +Authenticating Rocket 2 as a GitHub App and obtaining an access token +for the GitHub API should be automated, once the signing key is +available. Refer to the `GitHub key configuration +docs `__ for the required permissions. + +After doing this, remember to put your tunneled HTTPS URL with +``/webhook`` appended at the end into the “Webhook URL” box. Refer to +the `GitHub webhook configuration +docs `__ for the required subscriptions. + +6: Set Up Configuration +----------------------- + +Our repo already contains ``sample-env``, the main environmental +configuration file for the entire app, as well as the ``credentials/`` +directory, where you will put credential files like the GitHub app +private key. + +Please `read the configuration docs `__ for more details. + +7: Build and Run Rocket 2 +------------------------- + +This section assumes you already have installed Docker. Assuming you are +in the directory containing the Dockerfile, all you need to do to build +and run is the following two commands (run from the root of your project +directory): + +.. code:: bash + + scripts/docker_build.sh + scripts/docker_run_local.sh --env-file .env + +Optionally, for `local DynamoDB <#using-local-aws>`__: + +.. code:: bash + + scripts/docker_run_local.sh --env-file .env --network="host" + +The option +```--env-file`` `__ +lets you pass in your `configuration options `__. + +For the curious, you can take a look at the contents of the referenced +scripts above. Note that the options passed to ``-p`` in ``docker run`` +tell Docker what port to run Rocket on. ``0.0.0.0`` is the IP address +(in this case, localhost), the first ``5000`` is the port exposed inside +the container, and the second ``5000`` is the port exposed outside the +container. The port exposed outside the container can be changed (for +instance, if port 5000 is already in use in your local development +environment), but in that case ensure that your tunnel is running on the +same port. + +6.1: [Optional] Running without Docker +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We highly recommend building and running on Docker, but building every +time you make a tiny change can be inconvenient. If you would like to +run without building a new Docker image every time, you can do so with +``pipenv run launch``. This is in fact the same command Docker runs, but +if you run outside Docker, you may run into errors due to unexpected +changes in your local development environment. + +7: Configure Slack App Features +------------------------------- + +In addition to a bot user, there are a couple other features that need +to be enabled in the Slack app once the local instance of Rocket is +running. + +7.1: Add Event Subscriptions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In “Add features and functionality”, add event subscriptions. In +particular, under Request URL, submit the ngrok HTTPS URL with +``/slack/events`` appended to the end. Note that ngrok will generate a +new HTTPS URL every time it runs, so you will have to repeat this step +every time you launch ngrok. You will then have to enable workspace +and/or bot events that we want Rocket to listen for, like the +``team_join`` workspace event - ask the team for the most up-to-date +list of these. + +7.2: Add Slash Command +~~~~~~~~~~~~~~~~~~~~~~ + +In “Add features and functionality”, add a slash command. In particular, +under Request URL, submit the ngrok HTTPS URL with ``/slack/commands`` +appended to the end. For the actual command, anything will work, though +the final app will use ``/rocket``. Make sure you tick the box marked +“Escape channels, users, and links sent to your app”, or else none of +the @ signs will work properly! + +8: Testing +---------- + +This is the final and most important part: testing if it actually works +or not. Go to your Slack workspace and add Rocket (or whatever you named +your Slack bot) to the channel if you have yet to do so (just type +``@`` and Slack will ask if you want to invite the bot into +the channel). + +To test if Rocket is running, type the command: + +:: + + /rocket user help + +If you see a list of options, Rocket is working! + +8.1: Setting Up Admin Permissions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We currently haven’t finished the command to add a user to the database +or make them an admin, so we have to do it manually. + +First, determine your Slack ID by reading the logs. The logs are +formatted like so: + +:: + + {slackid_making_the_command}:{command_itself} + +The Slack IDs of other users will appear when you type ``@`` followed by +whatever the user’s handle is. Slack automatically converts that handle +into an ID. + +Then, you have an option of either using the AWS command-line interface +or using the AWS web interface. + +You should already have the command line interface installed via pipenv. +If not, run the command ``pipenv install --dev``. Note that to run +commands, you will either have to go into the pipenv environment (with +``pipenv shell``) or prefix every command with ``pipenv run``. Here is +the command to create a user with a: + +.. code:: bash + + # The following command is split into multiple lines because it is long. Make + # sure that the actal command isn't split into multiple lines because it may + # complicate things. + aws dynamodb put-item --table-name USERS_TABLE\ + --item '{"slack_id":{"S": "UE7PAG75L"}, + "permission_level":{"S": "admin"}}'\ + --endpoint-url http://localhost:8000 + +Replace ``USERS_TABLE`` with whatever name you set in ``config.toml``. + +Alternatively, you can directly edit the DynamoDB table via the AWS web +interface. Go to the DynamoDB service in the AWS web interface and open +the appropriate table. Click on the Items tab and then on “Create item”. +Make sure there’s a column for ``slack_id`` and ``permission_level``, +where ``slack_id`` is a ``String`` with the appropriate value and +``permission_level`` is a ``String`` with the value ``admin``. + +8.2: Viewing a User +~~~~~~~~~~~~~~~~~~~ + +:: + + /rocket user view + +The output of this command should be a stylish table displaying your +Slack id and permissions level. + +Now, you can continue with whatever testing you originally wanted to do. +Remember to rebulid your Docker image every time you make a change! diff --git a/docs/ProjectCommands.md b/docs/ProjectCommands.md deleted file mode 100644 index af70b416..00000000 --- a/docs/ProjectCommands.md +++ /dev/null @@ -1,85 +0,0 @@ -# Project Command Reference - -Commands to do with projects. Remember that parameters with whitespace -must be enclosed by quotation marks. - -## Options - -```sh -/rocket project {list, view, help, create, unassign, edit, assign, delete} -``` - -### List - -```sh -/rocket project list -``` - -Display a list of all projects. - -### View - -```sh -/rocket project view PROJECT_ID -``` - -Displays details of project. - -### Help - -```sh -/rocket project help -``` - -Displays options for `project` command. - -### Create (Team Lead and Admin only) - -```sh -/rocket project create GH_REPO GITHUB_TEAM_NAME [--name DISPLAY_NAME] -``` - -Creates a new project from the given repo. -Fails if the caller is not the team lead of the specified team or an admin. - -### Unassign (Team Lead and Admin only) - -```sh -/rocket project unassign PROJECT_ID -``` - -Unassigns the given project. -Fails if the caller is not the team lead of the team assigned to the project -or if the caller is not an admin. - -### Edit - -```sh -/rocket project edit PROJECT_ID [--name DISPLAY_NAME] -``` - -Edit the given project. - -### Assign (Team Lead and Admin only) - -```sh -/rocket project assign PROJECT_ID GITHUB_TEAM_NAME [-f] -``` - -Assigns the project to the team. Fails if another team is assigned the project. -If `-f` flag is given, can reassign even if -another team is already assigned the project. -Fails if the caller is not the team lead of the team to assign the project to -or if the caller is not an admin. - -### Delete (Team Lead and Admin only) - -```sh -/rocket project delete PROJECT_ID [-f] -``` - -Delete the project from database. An error occurs if the project is currently assigned. -If `-f` flag is given, can be deleted -even if a team is assigned. -Fails if the caller is not the team lead project's assigned team -or if the caller is not an admin. diff --git a/docs/ProjectCommands.rst b/docs/ProjectCommands.rst new file mode 100644 index 00000000..cd12c7be --- /dev/null +++ b/docs/ProjectCommands.rst @@ -0,0 +1,92 @@ +Project Command Reference +========================= + +Commands to do with projects. Remember that parameters with whitespace +must be enclosed by quotation marks. + +Options +------- + +.. code:: sh + + /rocket project {list, view, help, create, unassign, edit, assign, delete} + +List +~~~~ + +.. code:: sh + + /rocket project list + +Display a list of all projects. + +View +~~~~ + +.. code:: sh + + /rocket project view PROJECT_ID + +Displays details of project. + +Help +~~~~ + +.. code:: sh + + /rocket project help + +Displays options for ``project`` command. + +Create (Team Lead and Admin only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: sh + + /rocket project create GH_REPO GITHUB_TEAM_NAME [--name DISPLAY_NAME] + +Creates a new project from the given repo. Fails if the caller is not +the team lead of the specified team or an admin. + +Unassign (Team Lead and Admin only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: sh + + /rocket project unassign PROJECT_ID + +Unassigns the given project. Fails if the caller is not the team lead of +the team assigned to the project or if the caller is not an admin. + +Edit +~~~~ + +.. code:: sh + + /rocket project edit PROJECT_ID [--name DISPLAY_NAME] + +Edit the given project. + +Assign (Team Lead and Admin only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: sh + + /rocket project assign PROJECT_ID GITHUB_TEAM_NAME [-f] + +Assigns the project to the team. Fails if another team is assigned the +project. If ``-f`` flag is given, can reassign even if another team is +already assigned the project. Fails if the caller is not the team lead +of the team to assign the project to or if the caller is not an admin. + +Delete (Team Lead and Admin only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: sh + + /rocket project delete PROJECT_ID [-f] + +Delete the project from database. An error occurs if the project is +currently assigned. If ``-f`` flag is given, can be deleted even if a +team is assigned. Fails if the caller is not the team lead project’s +assigned team or if the caller is not an admin. diff --git a/docs/Qna.md b/docs/Qna.md deleted file mode 100644 index a7ae58cf..00000000 --- a/docs/Qna.md +++ /dev/null @@ -1,19 +0,0 @@ -# Questions and Answers - -**What is the `db` module?** -The database `db` module consists of the `facade` and the `dynamodb` database -we are using. - -**What is the `command` module?** -The `command` module is where the slack commands get parsed and passed on to the -backend so models can be created and the database can be populated. - -**What is the `model` module?** -The `model` module is where models are constructed. -Currently we have `Team` and `User` models. - -**How do `db`, `command`, `model` modules interact with each other?** -First a command is input through slack. Then, the input will be parsed so a -model can be populated. After the model gets populated, the model can then be -added into the db. The db contains a separate -table for each type of model. diff --git a/docs/Qna.rst b/docs/Qna.rst new file mode 100644 index 00000000..655cccdb --- /dev/null +++ b/docs/Qna.rst @@ -0,0 +1,18 @@ +Questions and Answers +===================== + +**What is the ``db`` module?** The database ``db`` module consists of +the ``facade`` and the ``dynamodb`` database we are using. + +**What is the ``command`` module?** The ``command`` module is where the +slack commands get parsed and passed on to the backend so models can be +created and the database can be populated. + +**What is the ``model`` module?** The ``model`` module is where models +are constructed. Currently we have ``Team`` and ``User`` models. + +**How do ``db``, ``command``, ``model`` modules interact with each +other?** First a command is input through slack. Then, the input will be +parsed so a model can be populated. After the model gets populated, the +model can then be added into the db. The db contains a separate table +for each type of model. diff --git a/docs/Requirements.md b/docs/Requirements.md deleted file mode 100644 index f8db872a..00000000 --- a/docs/Requirements.md +++ /dev/null @@ -1,39 +0,0 @@ -# Requirements - -## MVP - -Our MVP is essentially feature-parity with the original Rocket. -In particular, we should have: - -* An extensible Unix-style command system -* `user` command (member info) -* `team` command (team management) -* `help` command -* Permissions system - -All of these should be connected to a database, likely a cloud -database like DynamoDb or Firebase. - -We have decided *not* to pursue a full plugin-oriented architecture, -as this would severely complicate our work and most likely would not be used. - -## Stretch Goals - -* Currently Rocket does most of the work of managing the Launch Pad - Github organization. Replicating and extending this behaviour would - be our first priority after completing the MVP. -* More ways to access Rocket-the-service would be nice. In particular, - a command-line interface should be relatively easy to build. A - web-based dashboard would be useful, but likely too far outside scope. -* A reminders command has been specifically requested by the co-presidents. -* The co-presidents also have other feature requests that will be added - as Github issues. - -## Non-functional & Other Requirements - -* Rocket 2.0 will be containerized via [Docker](https://www.docker.com). -* All code will follow the [PEP8 style guide](http://pep8.org); - this will be automated with [pycodestyle](https://github.com/pycqa/pycodestyle). -* There should be automated tests for most behaviour, run with a CI system, - and code coverage should be collected and uploaded to [Codecov.io](https://codecov.io). -* The command system should be reasonably extensible. diff --git a/docs/Requirements.rst b/docs/Requirements.rst new file mode 100644 index 00000000..579dac80 --- /dev/null +++ b/docs/Requirements.rst @@ -0,0 +1,49 @@ +Requirements +============ + +MVP +--- + +Our MVP is essentially feature-parity with the original Rocket. In +particular, we should have: + +- An extensible Unix-style command system +- ``user`` command (member info) +- ``team`` command (team management) +- ``help`` command +- Permissions system + +All of these should be connected to a database, likely a cloud database +like DynamoDb or Firebase. + +We have decided *not* to pursue a full plugin-oriented architecture, as +this would severely complicate our work and most likely would not be +used. + +Stretch Goals +------------- + +- Currently Rocket does most of the work of managing the Launch Pad + Github organization. Replicating and extending this behaviour would + be our first priority after completing the MVP. +- More ways to access Rocket-the-service would be nice. In particular, + a command-line interface should be relatively easy to build. A + web-based dashboard would be useful, but likely too far outside + scope. +- A reminders command has been specifically requested by the + co-presidents. +- The co-presidents also have other feature requests that will be added + as Github issues. + +Non-functional & Other Requirements +----------------------------------- + +- Rocket 2.0 will be containerized via + `Docker `__. +- All code will follow the `PEP8 style guide `__; this + will be automated with + `pycodestyle `__. +- There should be automated tests for most behaviour, run with a CI + system, and code coverage should be collected and uploaded to + `Codecov.io `__. +- The command system should be reasonably extensible. diff --git a/docs/Scheduler.md b/docs/Scheduler.md deleted file mode 100644 index 8a2244cc..00000000 --- a/docs/Scheduler.md +++ /dev/null @@ -1,61 +0,0 @@ -# Scheduler Guide - -So, you want to write a module and add it to the ever-growing list of modules -that run periodically for rocket 2? Well, you have come to the right place. - -A very good example module can be found in the -`app/scheduler/modules/random_channel.py` source file. I recommend that you -read it before starting development (don't worry, it's very short). - -## Structure - -All scheduler modules are to be placed in the `app/scheduler/modules/` -directory. As Python source files, of course. These files should house the -module class. Every class must inherit `ModuleBase`. - -Since you inherit the `ModuleBase` class, you must implement the following -methods: - -**get\_job\_args**: A dictionary of job configuration arguments to be passed -into the scheduler. - -**do\_it**: A function that actually does the thing you want to do every time -the conditions you specified in the job configuration mentioned above. - -## Job arguments - -As you can see from the example, the following job arguments are returned: - -```js -{'trigger': 'cron', - 'day_of_week': 'sat', - 'hour': 12, - 'name': self.NAME} -``` - -Our trigger type is `cron`, meaning that it is supposed to fire once every time -the rest of the arguments fit. `day_of_week` means which day it is supposed to -fire. `hour` means which hour on that day it is supposed to fire. And every job -has to have a name, which is specified in the `name` argument. For a more -detailed look at the different types of arguments and different trigger types -that aren't discussed here, have a look at the [APScheduler -documentation][apdocs]. - -## Firing it - -The function `do_it` is called whenever it is time to execute the job. You can -use it to periodically message people, periodically check statistics, poll -Github, you name it. - -## Adding your module to the scheduler - -To actually have the scheduler execute and remember your module (and job), you -must add the job to the scheduler. This can be achieved by adding your module -into the scheduler via the function `__add_job` within the function -`__init_periodic_tasks`. You can see that we already have initialized our -beloved `RandomChannelPromoter` in that function, so just follow along with -your own module. - -And look! That wasn't all that bad now wasn't it?? - -[apdocs]: https://apscheduler.readthedocs.io/en/latest/modules/triggers/interval.html?highlight=intervaltrigger#apscheduler.triggers.interval.IntervalTrigger diff --git a/docs/Scheduler.rst b/docs/Scheduler.rst new file mode 100644 index 00000000..6c14b9d5 --- /dev/null +++ b/docs/Scheduler.rst @@ -0,0 +1,69 @@ +Scheduler Guide +=============== + +So, you want to write a module and add it to the ever-growing list of +modules that run periodically for rocket 2? Well, you have come to the +right place. + +A very good example module can be found in the +``app/scheduler/modules/random_channel.py`` source file. I recommend +that you read it before starting development (don’t worry, it’s very +short). + +Structure +--------- + +All scheduler modules are to be placed in the ``app/scheduler/modules/`` +directory. As Python source files, of course. These files should house +the module class. Every class must inherit ``ModuleBase``. + +Since you inherit the ``ModuleBase`` class, you must implement the +following methods: + +**get_job_args**: A dictionary of job configuration arguments to be +passed into the scheduler. + +**do_it**: A function that actually does the thing you want to do every +time the conditions you specified in the job configuration mentioned +above. + +Job arguments +------------- + +As you can see from the example, the following job arguments are +returned: + +.. code:: js + + {'trigger': 'cron', + 'day_of_week': 'sat', + 'hour': 12, + 'name': self.NAME} + +Our trigger type is ``cron``, meaning that it is supposed to fire once +every time the rest of the arguments fit. ``day_of_week`` means which +day it is supposed to fire. ``hour`` means which hour on that day it is +supposed to fire. And every job has to have a name, which is specified +in the ``name`` argument. For a more detailed look at the different +types of arguments and different trigger types that aren’t discussed +here, have a look at the `APScheduler +documentation `__. + +Firing it +--------- + +The function ``do_it`` is called whenever it is time to execute the job. +You can use it to periodically message people, periodically check +statistics, poll Github, you name it. + +Adding your module to the scheduler +----------------------------------- + +To actually have the scheduler execute and remember your module (and +job), you must add the job to the scheduler. This can be achieved by +adding your module into the scheduler via the function ``__add_job`` +within the function ``__init_periodic_tasks``. You can see that we +already have initialized our beloved ``RandomChannelPromoter`` in that +function, so just follow along with your own module. + +And look! That wasn’t all that bad now wasn’t it?? diff --git a/docs/Scripts.md b/docs/Scripts.md deleted file mode 100644 index ba9e0f83..00000000 --- a/docs/Scripts.md +++ /dev/null @@ -1,139 +0,0 @@ -# Scripts for Development - -There are a few scripts in the `scripts/` directory that aid in the development -of this project. - -## build\_check.sh - -```sh -scripts/build_check.sh -``` - -This is just the list of commands run to check the code for violations of Python -style. It also runs the tests, and is the script that is run in our Github CI. -Make sure to run before submitting a pull request! - -This script also checks to see if the user is running DynamoDB locally, and if -so, would include tests for it; if not, the tests that use DynamoDB will be -deselected. - -See [git hooks](#makefile-for-git-hooks). - -## port\_busy.py - -```sh -pipenv run python scripts/port_busy.py 8000 -``` - -This is to check if a port is busy on the machine you are running on. - -Used in place of `nmap` for automatically checking if the port used for local -instances of DynamoDB is in use. - -- Exits with 0 if the port is in use. -- Exits with 1 if there is an issue connecting with the port you provided. -- Exits with 2 if the 'port' you provided couldn't be converted to an integer. -- Exits with 3 if you didn't provide exactly 1 argument. -- Exits with 4 if the port is not already in use. - -## update.sh - -```sh -scripts/update.sh -``` - -This should be run whenever any change to `Pipfile` or `Pipfile.lock` occurs on -your local copy of a branch. It updates any changed dependencies into your -virtual environment. This is equivalent to the user running: - -```sh -pipenv sync --dev -``` - -Which, coincidentally, require the same number of characters to be typed. The -script should ideally be run after any instance of `git pull`. - -See [git hooks](#makefile-for-git-hooks). - -## download\_dynamodb\_and\_run.sh - -```sh -scripts/download_dynamodb_and_run.sh -``` - -This script downloads a copy of the latest local version of DynamoDB and forks -the process. It also sets up the environment in which you should run it in using -`scripts/setup_localaws.sh`. - -Please do not use this script; it is meant to be run by Github CI. Unless you -enjoy having to download and run multiple DynamoDB processes. - -## setup\_localaws.sh - -```sh -scripts/setup_localaws.sh -``` - -This script automatically sets up your environment to better benefit a local -instance of DynamoDB. Only should be run once by users (though running it -multiple times would not hurt too too much). It requires `aws` to be installed -through `pipenv`. - -## docker\_build.sh - -```sh -scripts/docker_build.sh -``` - -This script builds a docker image `rocket2-dev-img`, according to the -`Dockerfile`. Equivalent to: - -```sh -docker build -t rocket2-dev-img . -``` - -Make sure you have docker installed on your system beforehand. - -## docker\_run\_local.sh - -```sh -scripts/docker_run_local.sh -``` - -This script runs a local docker image on your system, port 5000. Equivalent to: - -```sh -docker run --rm -it -p 0.0.0.0:5000:5000 rocket2-dev-img -``` - -Make sure you have already built a `rocket2-dev-img`, or have run -`scripts/docker_build.sh` before-hand. `docker` must also be installed. - -## Makefile for Git Hooks - -```sh -cd scripts -make -``` - -This script simply installs the pre-commit hooks and post-merge hooks. -`build_check.sh` is copied to `.git/hooks/pre-commit`, and `update.sh` is copied -to `.git/hooks/post-merge`. - -After installation, every time you try to make a commit, all the tests will be -run automatically to ensure compliance. Every time you perform a `pull` or -`merge` or `rebase`, `pipenv` will try to sync all packages and dependencies. - -## Makefile for Documentation - -```sh -make clean html -``` - -This script builds all documentation and places the html into `_build/` -directory. Should mostly be used to test your documentation locally. Should be -run within a `pipenv shell` environment. - -We use Python `sphinx` to generate documentation from reStructuredText and -Markdown files in this project. To configure (and change versions for the -documentation), edit `conf.py`. `docs/index.rst` is the index for all documentation. diff --git a/docs/Scripts.rst b/docs/Scripts.rst new file mode 100644 index 00000000..d5561a2f --- /dev/null +++ b/docs/Scripts.rst @@ -0,0 +1,157 @@ +Scripts for Development +======================= + +There are a few scripts in the ``scripts/`` directory that aid in the +development of this project. + +build_check.sh +-------------- + +.. code:: sh + + scripts/build_check.sh + +This is just the list of commands run to check the code for violations +of Python style. It also runs the tests, and is the script that is run +in our Github CI. Make sure to run before submitting a pull request! + +This script also checks to see if the user is running DynamoDB locally, +and if so, would include tests for it; if not, the tests that use +DynamoDB will be deselected. + +See `git hooks <#makefile-for-git-hooks>`__. + +port_busy.py +------------ + +.. code:: sh + + pipenv run python scripts/port_busy.py 8000 + +This is to check if a port is busy on the machine you are running on. + +Used in place of ``nmap`` for automatically checking if the port used +for local instances of DynamoDB is in use. + +- Exits with 0 if the port is in use. +- Exits with 1 if there is an issue connecting with the port you + provided. +- Exits with 2 if the ‘port’ you provided couldn’t be converted to an + integer. +- Exits with 3 if you didn’t provide exactly 1 argument. +- Exits with 4 if the port is not already in use. + +update.sh +--------- + +.. code:: sh + + scripts/update.sh + +This should be run whenever any change to ``Pipfile`` or +``Pipfile.lock`` occurs on your local copy of a branch. It updates any +changed dependencies into your virtual environment. This is equivalent +to the user running: + +.. code:: sh + + pipenv sync --dev + +Which, coincidentally, require the same number of characters to be +typed. The script should ideally be run after any instance of +``git pull``. + +See `git hooks <#makefile-for-git-hooks>`__. + +download_dynamodb_and_run.sh +---------------------------- + +.. code:: sh + + scripts/download_dynamodb_and_run.sh + +This script downloads a copy of the latest local version of DynamoDB and +forks the process. It also sets up the environment in which you should +run it in using ``scripts/setup_localaws.sh``. + +Please do not use this script; it is meant to be run by Github CI. +Unless you enjoy having to download and run multiple DynamoDB processes. + +setup_localaws.sh +----------------- + +.. code:: sh + + scripts/setup_localaws.sh + +This script automatically sets up your environment to better benefit a +local instance of DynamoDB. Only should be run once by users (though +running it multiple times would not hurt too too much). It requires +``aws`` to be installed through ``pipenv``. + +docker_build.sh +--------------- + +.. code:: sh + + scripts/docker_build.sh + +This script builds a docker image ``rocket2-dev-img``, according to the +``Dockerfile``. Equivalent to: + +.. code:: sh + + docker build -t rocket2-dev-img . + +Make sure you have docker installed on your system beforehand. + +docker_run_local.sh +------------------- + +.. code:: sh + + scripts/docker_run_local.sh + +This script runs a local docker image on your system, port 5000. +Equivalent to: + +.. code:: sh + + docker run --rm -it -p 0.0.0.0:5000:5000 rocket2-dev-img + +Make sure you have already built a ``rocket2-dev-img``, or have run +``scripts/docker_build.sh`` before-hand. ``docker`` must also be +installed. + +Makefile for Git Hooks +---------------------- + +.. code:: sh + + cd scripts + make + +This script simply installs the pre-commit hooks and post-merge hooks. +``build_check.sh`` is copied to ``.git/hooks/pre-commit``, and +``update.sh`` is copied to ``.git/hooks/post-merge``. + +After installation, every time you try to make a commit, all the tests +will be run automatically to ensure compliance. Every time you perform a +``pull`` or ``merge`` or ``rebase``, ``pipenv`` will try to sync all +packages and dependencies. + +Makefile for Documentation +-------------------------- + +.. code:: sh + + make clean html + +This script builds all documentation and places the html into +``_build/`` directory. Should mostly be used to test your documentation +locally. Should be run within a ``pipenv shell`` environment. + +We use Python ``sphinx`` to generate documentation from reStructuredText +and Markdown files in this project. To configure (and change versions +for the documentation), edit ``conf.py``. ``docs/index.rst`` is the +index for all documentation. diff --git a/docs/TeamCommands.md b/docs/TeamCommands.md deleted file mode 100644 index bf5054c8..00000000 --- a/docs/TeamCommands.md +++ /dev/null @@ -1,116 +0,0 @@ -# Team Command Reference - -Commands that manipulate team data. Remember that parameters with whitespace -must be enclosed by quotation marks. - -## Options - -```sh -/rocket team {list, view, help, create, edit, add, remove, lead, delete} -``` - -### List - -```sh -/rocket team list -``` - -Display a list of Github team names and display names of all teams. - -### View - -```sh -/rocket team view GITHUB_TEAM_NAME -``` - -Display information and members of a specific team. - -### Help - -```sh -/rocket team help -``` - -Display options for team commands. - -### Create (Team Lead and Admin only) - -```sh -/rocket team create GITHUB_TEAM_NAME [--name DISPLAY_NAME] - [--platform PLATFORM] - [--channel CHANNEL] - [--lead SLACK_ID] -``` - -Create a new team with a Github team name and optional display name. The user -who runs the command will be automatically added to team as Team Lead. If the -`--lead` flag is used, user with `SLACK_ID` will be added as Team Lead -instead. If the `--channel` flag is used, all members in specified -channel will be added. 'SLACK_ID' is the `@`-name, for easy slack autocomplete. - -We use Github API to create the team on Github. - -The Github team name cannot contain spaces. - -```sh -/rocket team create "struddle-bouts" --name "Struddle Bouts" --channel @brussel_sprouts -``` - -### Edit (Team Lead\* and Admin only) - -```sh -/rocket team edit GITHUB_TEAM_NAME [--name DISPLAY_NAME] [--platform PLATFORM] -``` - -Edit the properties of a specific team. Team Leads can only edit the teams that -they are a part of, but admins can edit any teams. - -### Add (Team Lead\* and Admin only) - -```sh -/rocket team add GITHUB_TEAM_NAME SLACK_ID -``` - -Add a user to the team. Team Leads can only add users into teams that they are a -part of, but admins can add users to any team. `SLACK_ID` is the `@`-name, for -easy slack autocomplete. - -Users will be added to the teams on Github as well. - -```sh -/rocket team add struddle-bouts @s_universe -``` - -### Remove (Team Lead\* and Admin only) - -```sh -/rocket team remove GITHUB_TEAM_NAME SLACK_ID -``` - -Remove a user from a team, removes them as Team Lead if they were one. Team -Leads can only remove users from teams that they are a part of, but admins can -remove users from any team. `SLACK_ID` is the `@`-name, for easy slack -autocomplete. - -Users will be removed from the teams on Github as well. - -### Lead (Team Lead\* and Admin only) - -```sh -/rocket team lead GITHUB_TEAM_NAME SLACK_ID [--remove] -``` - -Adds a user as Team Lead, and adds them to team if not already added. -If `--remove` flag is used, will remove user as Team Lead, but not from the team. -Team Leads can only promote/demote users in teams that they are part -of, but admins can promote/demote users in any team. 'SLACK_ID' is the -`@`-name, for easy slack autocomplete. - -### Delete (Team Lead\* and Admin only) - -```sh -/rocket team delete GITHUB_TEAM_NAME -``` - -Permanently delete a team. Team Leads can only delete teams that they are a part -of, but admins can delete any team. diff --git a/docs/TeamCommands.rst b/docs/TeamCommands.rst new file mode 100644 index 00000000..bde7a62e --- /dev/null +++ b/docs/TeamCommands.rst @@ -0,0 +1,128 @@ +Team Command Reference +====================== + +Commands that manipulate team data. Remember that parameters with +whitespace must be enclosed by quotation marks. + +Options +------- + +.. code:: sh + + /rocket team {list, view, help, create, edit, add, remove, lead, delete} + +List +~~~~ + +.. code:: sh + + /rocket team list + +Display a list of Github team names and display names of all teams. + +View +~~~~ + +.. code:: sh + + /rocket team view GITHUB_TEAM_NAME + +Display information and members of a specific team. + +Help +~~~~ + +.. code:: sh + + /rocket team help + +Display options for team commands. + +Create (Team Lead and Admin only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: sh + + /rocket team create GITHUB_TEAM_NAME [--name DISPLAY_NAME] + [--platform PLATFORM] + [--channel CHANNEL] + [--lead SLACK_ID] + +Create a new team with a Github team name and optional display name. The +user who runs the command will be automatically added to team as Team +Lead. If the ``--lead`` flag is used, user with ``SLACK_ID`` will be +added as Team Lead instead. If the ``--channel`` flag is used, all +members in specified channel will be added. ‘SLACK_ID’ is the +``@``-name, for easy slack autocomplete. + +We use Github API to create the team on Github. + +The Github team name cannot contain spaces. + +.. code:: sh + + /rocket team create "struddle-bouts" --name "Struddle Bouts" --channel @brussel_sprouts + +Edit (Team Lead\* and Admin only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: sh + + /rocket team edit GITHUB_TEAM_NAME [--name DISPLAY_NAME] [--platform PLATFORM] + +Edit the properties of a specific team. Team Leads can only edit the +teams that they are a part of, but admins can edit any teams. + +Add (Team Lead\* and Admin only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: sh + + /rocket team add GITHUB_TEAM_NAME SLACK_ID + +Add a user to the team. Team Leads can only add users into teams that +they are a part of, but admins can add users to any team. ``SLACK_ID`` +is the ``@``-name, for easy slack autocomplete. + +Users will be added to the teams on Github as well. + +.. code:: sh + + /rocket team add struddle-bouts @s_universe + +Remove (Team Lead\* and Admin only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: sh + + /rocket team remove GITHUB_TEAM_NAME SLACK_ID + +Remove a user from a team, removes them as Team Lead if they were one. +Team Leads can only remove users from teams that they are a part of, but +admins can remove users from any team. ``SLACK_ID`` is the ``@``-name, +for easy slack autocomplete. + +Users will be removed from the teams on Github as well. + +Lead (Team Lead\* and Admin only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: sh + + /rocket team lead GITHUB_TEAM_NAME SLACK_ID [--remove] + +Adds a user as Team Lead, and adds them to team if not already added. If +``--remove`` flag is used, will remove user as Team Lead, but not from +the team. Team Leads can only promote/demote users in teams that they +are part of, but admins can promote/demote users in any team. ‘SLACK_ID’ +is the ``@``-name, for easy slack autocomplete. + +Delete (Team Lead\* and Admin only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: sh + + /rocket team delete GITHUB_TEAM_NAME + +Permanently delete a team. Team Leads can only delete teams that they +are a part of, but admins can delete any team. diff --git a/docs/Testing.md b/docs/Testing.md deleted file mode 100644 index 006354d6..00000000 --- a/docs/Testing.md +++ /dev/null @@ -1,58 +0,0 @@ -# Testing - -> **Warning**: This is no longer the most up-to-date documentation on how -> testing is done here. You may want to head over [here][full-testing] for more -> up-to-date documentation on how we test things. *You have been warned....* - -## Running Pytest Efficiently - -Test Driven Development... we hear professors preach about it during lectures -but we never got an opportunity to put it to good use until Rocket2 came along. -Unfortunately we got over excited and wrote A LOT of tests. Running them all -every time is a bit painful, that's where `@pytest.mark` comes in. `pytest.mark` -allows you to label your tests to run them in groups. - -We only have tests that test the functions by themselves. Features that involve -multiple parts (such as a new command involving Slack, Github, and the database) -should be tested manually as well. - -### Run all the tests - -`pytest` - -### Run only db tests - -`pytest -m db` - -### Run all tests except database tests - -`pytest -m "not db"` - -## Testing the Database - -What are environment variables? Variables for the environment of course! These -variables set up the environment for testing. Rocket2 uses them because we have -both a local and a sever DynamoDB database and each require an extra variable to -get everything working. - -### Run local DynamoDB - -We use the `AWS_LOCAL` environment variable to indicate if we want to run -DynamoDB locally or on a server. Change `AWS_LOCAL = 'True'` to use local -DynamoDB. - -If `AWS_LOCAL == 'True'` but you did not start an instance of local DynamoDB, -`scripts/build_check.sh` will automatically skip all database tests. - -This is the recommended way for unit testing. - -### Run server DynamoDB - -To run the server DynamoDB we need to set the `AWS_REGION` and obtain -`AWS_ACCESS_KEYID`, `AWS_SECRET_KEY`, and `GITHUB_KEY`. - -This is the recommended way for testing everything (not unit testing, but -testing the slack commands themselves). Click [here][full-testing] to learn how -to set up a full development environment (including the testing part). - -[full-testing]: LocalDevelopmentGuide.html diff --git a/docs/Testing.rst b/docs/Testing.rst new file mode 100644 index 00000000..3127bc79 --- /dev/null +++ b/docs/Testing.rst @@ -0,0 +1,68 @@ +Testing +======= + + **Warning**: This is no longer the most up-to-date documentation on + how testing is done here. You may want to head over + `here `__ for more up-to-date + documentation on how we test things. *You have been warned….* + +Running Pytest Efficiently +-------------------------- + +Test Driven Development… we hear professors preach about it during +lectures but we never got an opportunity to put it to good use until +Rocket2 came along. Unfortunately we got over excited and wrote A LOT of +tests. Running them all every time is a bit painful, that’s where +``@pytest.mark`` comes in. ``pytest.mark`` allows you to label your +tests to run them in groups. + +We only have tests that test the functions by themselves. Features that +involve multiple parts (such as a new command involving Slack, Github, +and the database) should be tested manually as well. + +Run all the tests +~~~~~~~~~~~~~~~~~ + +``pytest`` + +Run only db tests +~~~~~~~~~~~~~~~~~ + +``pytest -m db`` + +Run all tests except database tests +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``pytest -m "not db"`` + +Testing the Database +-------------------- + +What are environment variables? Variables for the environment of course! +These variables set up the environment for testing. Rocket2 uses them +because we have both a local and a sever DynamoDB database and each +require an extra variable to get everything working. + +Run local DynamoDB +~~~~~~~~~~~~~~~~~~ + +We use the ``AWS_LOCAL`` environment variable to indicate if we want to +run DynamoDB locally or on a server. Change ``AWS_LOCAL = 'True'`` to +use local DynamoDB. + +If ``AWS_LOCAL == 'True'`` but you did not start an instance of local +DynamoDB, ``scripts/build_check.sh`` will automatically skip all +database tests. + +This is the recommended way for unit testing. + +Run server DynamoDB +~~~~~~~~~~~~~~~~~~~ + +To run the server DynamoDB we need to set the ``AWS_REGION`` and obtain +``AWS_ACCESS_KEYID``, ``AWS_SECRET_KEY``, and ``GITHUB_KEY``. + +This is the recommended way for testing everything (not unit testing, +but testing the slack commands themselves). Click +`here `__ to learn how to set up a full +development environment (including the testing part). diff --git a/docs/UserCommands.md b/docs/UserCommands.md deleted file mode 100644 index c0b7c664..00000000 --- a/docs/UserCommands.md +++ /dev/null @@ -1,77 +0,0 @@ -# User Command Reference - -Commands that manipulate user data. Remember that parameters with whitespace -must be enclosed in quotation marks. - -## Options - -```sh -/rocket user {add, edit, view, help, delete} -``` - -### Add - -```sh -/rocket user add [-f|--force] -``` - -Add the current user into the database. This command by default does not -overwrite users that have already been entered into the database. By using the -`-f` flag, you force `rocket2` to overwrite the entry in the database, if any. - -### Edit - -```sh -/rocket user edit [--name NAME] [--email EMAIL] [--pos POSITION] - [--github GITHUB_HANDLE] [--major MAJOR] - [--bio BIOGRAPHY] - [--permission {member,team_lead,admin}] -``` - -Allows user to edit their Launch Pad profile. Admins and team leads can edit -another user's Launch Pad profile by using `[--username SLACKID]` option. -`SLACK_ID` is the `@`-name, for easy slack autocomplete. - -If a user edits their Github handle, rocket will also add the handle to Launch -Pad's Github organization. - -```sh -# Normal use -/rocket user edit --name "Steven Universe" --email "su@gmail.com" - -# Admin/Team lead use -/rocket user edit --username @s_universe --name "Steven Universe" -``` - -Admins can easily promote other admins or team leads. - -```sh -/rocket user edit --username @s_universe --permission admin -``` - -### View - -```sh -/rocket user view [SLACKID] -``` - -Display information about a user. `SLACK_ID` is the `@`-name, for easy slack -autocomplete. If `SLACK_ID` is not specified, this command displays information -about the one who ran the command instead. - -### Help - -```sh -/rocket user help -``` - -Display options for the user commands. - -### Delete (Admin only) - -```sh -/rocket user delete MEMBER_ID -``` - -Permanently delete a member's Launch Pad Profile. Can only be used by admins. -`MEMBER_ID` is the `@`-name, for easy slack autocomplete. diff --git a/docs/UserCommands.rst b/docs/UserCommands.rst new file mode 100644 index 00000000..ef37c2c6 --- /dev/null +++ b/docs/UserCommands.rst @@ -0,0 +1,85 @@ +User Command Reference +====================== + +Commands that manipulate user data. Remember that parameters with +whitespace must be enclosed in quotation marks. + +Options +------- + +.. code:: sh + + /rocket user {add, edit, view, help, delete} + +Add +~~~ + +.. code:: sh + + /rocket user add [-f|--force] + +Add the current user into the database. This command by default does not +overwrite users that have already been entered into the database. By +using the ``-f`` flag, you force ``rocket2`` to overwrite the entry in +the database, if any. + +Edit +~~~~ + +.. code:: sh + + /rocket user edit [--name NAME] [--email EMAIL] [--pos POSITION] + [--github GITHUB_HANDLE] [--major MAJOR] + [--bio BIOGRAPHY] + [--permission {member,team_lead,admin}] + +Allows user to edit their Launch Pad profile. Admins and team leads can +edit another user’s Launch Pad profile by using ``[--username SLACKID]`` +option. ``SLACK_ID`` is the ``@``-name, for easy slack autocomplete. + +If a user edits their Github handle, rocket will also add the handle to +Launch Pad’s Github organization. + +.. code:: sh + + # Normal use + /rocket user edit --name "Steven Universe" --email "su@gmail.com" + + # Admin/Team lead use + /rocket user edit --username @s_universe --name "Steven Universe" + +Admins can easily promote other admins or team leads. + +.. code:: sh + + /rocket user edit --username @s_universe --permission admin + +View +~~~~ + +.. code:: sh + + /rocket user view [SLACKID] + +Display information about a user. ``SLACK_ID`` is the ``@``-name, for +easy slack autocomplete. If ``SLACK_ID`` is not specified, this command +displays information about the one who ran the command instead. + +Help +~~~~ + +.. code:: sh + + /rocket user help + +Display options for the user commands. + +Delete (Admin only) +~~~~~~~~~~~~~~~~~~~ + +.. code:: sh + + /rocket user delete MEMBER_ID + +Permanently delete a member’s Launch Pad Profile. Can only be used by +admins. ``MEMBER_ID`` is the ``@``-name, for easy slack autocomplete. diff --git a/index.rst b/index.rst index 67bf8c0e..31875108 100644 --- a/index.rst +++ b/index.rst @@ -4,37 +4,37 @@ :hidden: self - CONTRIBUTING.md - LICENSE.md + CONTRIBUTING + LICENSE .. toctree:: :caption: Tutorials :hidden: - docs/GettingStarted.md - docs/Testing.md - docs/LocalDevelopmentGuide.md - docs/Scheduler.md + docs/GettingStarted + docs/Testing + docs/LocalDevelopmentGuide + docs/Scheduler .. toctree:: :caption: How Everything Works :hidden: - docs/Scripts.md - docs/Database.md - docs/Config.md - docs/Requirements.md - docs/Deployment.md - docs/Qna.md + docs/Scripts + docs/Database + docs/Config + docs/Requirements + docs/Deployment + docs/Qna .. toctree:: :caption: Plugin Reference :hidden: - docs/UserCommands.md - docs/TeamCommands.md - docs/ProjectCommands.md - docs/KarmaCommands.md + docs/UserCommands + docs/TeamCommands + docs/ProjectCommands + docs/KarmaCommands .. toctree:: :caption: API Documentation From 570ac6178d61402bae116a9d056c4edaeefd7338 Mon Sep 17 00:00:00 2001 From: Cheuk Yin Ng Date: Thu, 24 Sep 2020 21:11:59 -0700 Subject: [PATCH 6/7] fix: convert everything to rst, basically --- CODE_OF_CONDUCT.md | 77 ----------------------------- CODE_OF_CONDUCT.rst | 87 +++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 115 -------------------------------------------- LICENSE.md | 23 --------- README.md | 93 ----------------------------------- README.rst | 110 ++++++++++++++++++++++++++++++++++++++++++ conf.py | 26 ++-------- index.rst | 2 +- 8 files changed, 201 insertions(+), 332 deletions(-) delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CODE_OF_CONDUCT.rst delete mode 100644 CONTRIBUTING.md delete mode 100644 LICENSE.md delete mode 100644 README.md create mode 100644 README.rst diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index b067f0e3..00000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,77 +0,0 @@ -# Contributor Covenant 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, sex characteristics, gender identity and expression, -level of experience, education, socio-economic status, 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 project or its community. Examples of -representing a 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 a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at team@ubclaunchpad.com. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and 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's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 1.4, available [here][ccovenant]. - -For answers to common questions about this code of conduct, see the [faq][faq]. - -[faq]: https://www.contributor-covenant.org/faq -[ccovenant]: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html -[homepage]: https://www.contributor-covenant.org diff --git a/CODE_OF_CONDUCT.rst b/CODE_OF_CONDUCT.rst new file mode 100644 index 00000000..fc063fe2 --- /dev/null +++ b/CODE_OF_CONDUCT.rst @@ -0,0 +1,87 @@ +Contributor Covenant 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, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, 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 project or its community. +Examples of representing a 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 a project may be further defined and +clarified by project maintainers. + +Enforcement +----------- + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported by contacting the project team at team@ubclaunchpad.com. All +complaints will be reviewed and investigated and will result in a +response that is deemed necessary and 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’s leadership. + +Attribution +----------- + +This Code of Conduct is adapted from the `Contributor +Covenant `__, version 1.4, +available +`here `__. + +For answers to common questions about this code of conduct, see the +`faq `__. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 0bd48409..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,115 +0,0 @@ -# Contributing - -This document contains important details for anyone contributing to Rocket 2. - -## Opening an Issue - -If you see a bug or have a feature request, please [open an issue][issues]! -That being said, make sure to do a quick search first - there may already be an -issue that covers it. - -When creating a new issue, please add a label describing the issue; the most -relevant are probably "Bug" and "Feature request". - -**If you are going to work on an issue, please assign yourself to it, and -unassign yourself if you stop working on it.** - -If you are not planning to work on a new issue, please also add it to the -Rocket 2.0 project; this will automatically add it to our Kanban board's -backlog, where we can review it in a future sprint. - -## Setting up branches - -Before you make any changes, you should first set up your own branch. It is -common convention to name your branch: - -``` -/#- -``` - -So if your issue is [#153 Read from configuration][#153], you would name it -`rwblickhan/#153-read-from-config`. The name needs to be concise, descriptive, -and, well, have your name and number, so to speak. - -## Before-Pull-Request checklist - -- All tests and style and docs checks pass (`scripts/build_check.sh`) -- The Github build passes (Github will build your commit when you push it) -- Your code is presentable and you have **not** committed extra files (think - your credentials, IDE config files, cached directories, build directories, - etc.) -- You've written unit tests for the changes you've made, and that they cover - all the code you wrote (or effectively all, given the circumstances) - -We use `codecov` to check code coverage, but you can easily check the code -coverage using the `scripts/build_check.sh` script. The coverage should be -displayed after the unit tests are run. - -## Submitting a Pull Request - -We appreciate pull requests of any size or scope. - -Please use a clear, descriptive title for your pull request and fill out the -pull request template with as much detail as you can. In particular, all pull -requests should be linked to one or more issues - if a relevant issue does not -exist, please create one as described above. - -All pull requests must be code reviewed. Currently the code is owned by the -[brussel-sprouts][bs] team at UBC Launch Pad; at least one member of the team -must approve the pull request before it can be merged. - -All pull requests must pass our Github build before they can be merged. The -Github build checks for: - -- Passing unit tests (via [pytest](https://pytest.org)) -- Minimum code coverage of unit tests (via [Codecov.io](https://codecov.io/)) -- Code linting (via [flake8](https://flake8.readthedocs.io/en/latest/)) -- PEP8 code style (via [pycodestyle](http://pycodestyle.pycqa.org/en/latest/)) -- Correctly-formatted docstrings (via [pydocstyle](http://www.pydocstyle.org/en/2.1.1/)) -- Correctly-formatted Markdown documentation (via [mdl](https://github.com/markdownlint/markdownlint)) - -All of these checks are conveniently done using the `scripts/build_check.sh` as -mentioned above. - -Remember to add the label `Ready for Review`. - -After your pull request has been approved and the Github build passes, it can -be merged into `master`. Please do so with an ordinary merge commit, not a -rebase or squash merge. - -### Work in progress (WIP) pull requests - -Sometimes, it may be more appropriate to submit a pull request that you are -working on, just to say that you are working on something (or so that you can -get some initial feedback on your work). In that case, it can be a good idea to -submit a pull request marked WIP. The convention here is to prepend `[WIP]` in -the title of the request, and to further mark it with the label `WIP`. - -## Updating an Outdated Pull Request - -If changes have been merged between when you started work on your branch and -when your pull request was approved, you will have to update your branch. The -preferred way to do so is with a rebase. - -Assuming you are on your working branch: - -```bash -git pull origin master -git rebase master -``` - -If you have changed files that were also changed in the intervening merge, `git -rebase` may report merge conflicts. If this happens, don't panic! Use `git -status` and `git diff` to determine which files conflict and where, use an -editor to fix the conflicts, then stage the formerly-conflicting files with -`git add FILE`. Finally, use `git rebase --continue` to apply the fix and -continue rebasing. Note that you may have to fix conflicts multiple times in a -single rebase. - -It is also a good idea to replace the label `Ready for Review` with `Ready for -Re-Review` for clarity. - -[prs]: https://rocket2.rtfd.io/en/latest/docs/MyFirstPullRequest.html -[issues]: https://github.com/ubclaunchpad/rocket2/issues -[#153]: https://github.com/ubclaunchpad/rocket2/issues/153 -[bs]: https://github.com/orgs/ubclaunchpad/teams/brussel-sprouts diff --git a/LICENSE.md b/LICENSE.md deleted file mode 100644 index 54c34b55..00000000 --- a/LICENSE.md +++ /dev/null @@ -1,23 +0,0 @@ -# License - -MIT License - -Copyright (c) 2018 UBC Launch Pad - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/README.md b/README.md deleted file mode 100644 index a83a2254..00000000 --- a/README.md +++ /dev/null @@ -1,93 +0,0 @@ -# 🚀 Rocket 2 - -[![codecov](https://codecov.io/gh/ubclaunchpad/rocket2/branch/master/graph/badge.svg)](https://codecov.io/gh/ubclaunchpad/rocket2) -[![Deployed with Inertia](https://img.shields.io/badge/deploying%20with-inertia-blue.svg)](https://github.com/ubclaunchpad/inertia) -[![Documentation Status](https://readthedocs.org/projects/rocket2/badge/?version=latest)](https://rocket2.readthedocs.io/en/latest/?badge=latest) - -Rocket 2 is a from-the-ground-up rebuild of [Rocket](https://github.com/ubclaunchpad/rocket), -UBC Launch Pad's in-house management Slack bot. - -## Developer Installation - -We use [pipenv](https://pipenv.readthedocs.io/en/latest/) for dependency management. - -```bash -git clone https://github.com/ubclaunchpad/rocket2.git -cd rocket2/ -pip install pipenv -pipenv install --dev -``` - -`pipenv` will manage a [virtualenv](https://virtualenv.pypa.io/en/stable/), -so interacting with the program or using the development tools has to be done -through pipenv, like so: - -```bash -pipenv run pycodestyle . -``` - -This can get inconvenient, so you can instead create a shell that runs in the managed -environment like so: - -```bash -pipenv shell -``` - -and then commands like `pycodestyle` and `pytest` can be run like normal. - -Additionally, we use Github Actions as a CI system. To run the same checks -locally, we provide `scripts/build_check.sh`; this can be run with: - -```bash -./scripts/build_check.sh -``` - -The above tests would be run with the assumption that other applications, such -as a local instance of DynamoDB, is also running. To run tests that explicitly do -**not** involve the running of any database, run pytest with the following arguments: - -```bash -pytest -m "not db" -``` - -You can also install it as a -[pre-commit hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) for git: - -```bash -cd scripts/ -make install -``` - -Note that testing alongside a real Slack workspace, DynamoDB, and so on requires -quite a bit more setup. For a full guide to developer installation, see our -[local development guide](https://rocket2.readthedocs.io/en/latest/docs/LocalDevelopmentGuide.html). - -### Running DynamoDB Locally - -Some tests assume the existence of a local DynamoDB database. These are -primarily for automated testing, like on Github Actions CI, but if you would -like to run them yourself or are developing new tests, you can run as follows: - -```bash -wget https://s3-us-west-2.amazonaws.com/dynamodb-local/dynamodb_local_latest.tar.gz -mkdir DynamoDB -tar -xvf dynamodb_local_latest.tar.gz --directory DynamoDB - -# Configure AWS -scripts/setup_localaws.sh - -# Run DynamoDB through Java -cd DynamoDB/ -java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDb -# Open a new terminal to continue interacting -``` - -For a more sandboxed approach, you can use Docker and docker-compose to spin -up a local DynamoDB instance: - -```bash -docker-compose -f sandbox.yml up -``` - -You can then point a Rocket instance at this DynamoDB database by setting -`AWS_LOCAL=True`. diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..bd6a1e09 --- /dev/null +++ b/README.rst @@ -0,0 +1,110 @@ +🚀 Rocket 2 +=========== + +|codecov| |Deployed with Inertia| |Documentation Status| + +Rocket 2 is a from-the-ground-up rebuild of +`Rocket `__, UBC Launch Pad’s +in-house management Slack bot. + +Developer Installation +---------------------- + +We use `pipenv `__ for +dependency management. + +.. code:: bash + + git clone https://github.com/ubclaunchpad/rocket2.git + cd rocket2/ + pip install pipenv + pipenv install --dev + +``pipenv`` will manage a +`virtualenv `__, so interacting +with the program or using the development tools has to be done through +pipenv, like so: + +.. code:: bash + + pipenv run pycodestyle . + +This can get inconvenient, so you can instead create a shell that runs +in the managed environment like so: + +.. code:: bash + + pipenv shell + +and then commands like ``pycodestyle`` and ``pytest`` can be run like +normal. + +Additionally, we use Github Actions as a CI system. To run the same +checks locally, we provide ``scripts/build_check.sh``; this can be run +with: + +.. code:: bash + + ./scripts/build_check.sh + +The above tests would be run with the assumption that other +applications, such as a local instance of DynamoDB, is also running. To +run tests that explicitly do **not** involve the running of any +database, run pytest with the following arguments: + +.. code:: bash + + pytest -m "not db" + +You can also install it as a `pre-commit +hook `__ for +git: + +.. code:: bash + + cd scripts/ + make install + +Note that testing alongside a real Slack workspace, DynamoDB, and so on +requires quite a bit more setup. For a full guide to developer +installation, see our `local development +guide `__. + +Running DynamoDB Locally +~~~~~~~~~~~~~~~~~~~~~~~~ + +Some tests assume the existence of a local DynamoDB database. These are +primarily for automated testing, like on Github Actions CI, but if you +would like to run them yourself or are developing new tests, you can run +as follows: + +.. code:: bash + + wget https://s3-us-west-2.amazonaws.com/dynamodb-local/dynamodb_local_latest.tar.gz + mkdir DynamoDB + tar -xvf dynamodb_local_latest.tar.gz --directory DynamoDB + + # Configure AWS + scripts/setup_localaws.sh + + # Run DynamoDB through Java + cd DynamoDB/ + java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDb + # Open a new terminal to continue interacting + +For a more sandboxed approach, you can use Docker and docker-compose to +spin up a local DynamoDB instance: + +.. code:: bash + + docker-compose -f sandbox.yml up + +You can then point a Rocket instance at this DynamoDB database by +setting ``AWS_LOCAL=True``. + +.. |codecov| image:: https://codecov.io/gh/ubclaunchpad/rocket2/branch/master/graph/badge.svg + :target: https://codecov.io/gh/ubclaunchpad/rocket2 +.. |Deployed with Inertia| image:: https://img.shields.io/badge/deploying%20with-inertia-blue.svg + :target: https://github.com/ubclaunchpad/inertia +.. |Documentation Status| image:: https://readthedocs.org/projects/rocket2/badge/?version=latest + :target: https://rocket2.readthedocs.io/en/latest/?badge=latest diff --git a/conf.py b/conf.py index bf4e24f7..57167e79 100644 --- a/conf.py +++ b/conf.py @@ -13,7 +13,6 @@ """ import os import sys -import sphinx sys.path.insert(0, os.path.abspath('.')) @@ -24,9 +23,9 @@ author = 'UBC Launch Pad' # The short X.Y version -version = '0.0' +version = '1.0' # The full version, including alpha/beta/rc tags -release = '0.0.0-alpha' +release = '1.0.0' # -- General configuration --------------------------------------------------- @@ -41,14 +40,13 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx_autodoc_typehints', - 'm2r', ] # Add any paths that contain templates here, relative to this directory. templates_path = ['docs/_templates'] # The suffix(es) of source filenames. -source_suffix = ['.rst', '.md'] +source_suffix = ['.rst'] # The master toctree document. master_doc = 'index' @@ -174,24 +172,6 @@ epub_exclude_files = ['search.html'] -def monkeypatch(cls): - """ decorator to monkey-patch methods """ - def decorator(f): - method = f.__name__ - old_method = getattr(cls, method) - setattr(cls, method, lambda self, *args, **kwargs: f(old_method, self, *args, **kwargs)) - return decorator - -# workaround until https://github.com/miyakogi/m2r/pull/55 is merged -@monkeypatch(sphinx.registry.SphinxComponentRegistry) -def add_source_parser(_old_add_source_parser, self, *args, **kwargs): - # signature is (parser: Type[Parser], **kwargs), but m2r expects - # the removed (str, parser: Type[Parser], **kwargs). - if isinstance(args[0], str): - args = args[1:] - return _old_add_source_parser(self, *args, **kwargs) - - # -- Extension configuration ------------------------------------------------- def skip(app, what, name, obj, autoskip, options): """Make sure we don't skip __init__ functions.""" diff --git a/index.rst b/index.rst index 31875108..37965356 100644 --- a/index.rst +++ b/index.rst @@ -1,4 +1,4 @@ -.. mdinclude:: README.md +.. include:: README.rst .. toctree:: :hidden: From 566b541dbac256f4c34b0e9ba656dcd8aaea28e9 Mon Sep 17 00:00:00 2001 From: Cheuk Yin Ng Date: Thu, 24 Sep 2020 21:19:43 -0700 Subject: [PATCH 7/7] feat: remove mdl checks --- .github/workflows/master.yml | 1 - .github/workflows/pythonpackage.yml | 1 - CONTRIBUTING.rst | 2 -- scripts/build_check.sh | 1 - 4 files changed, 5 deletions(-) diff --git a/.github/workflows/master.yml b/.github/workflows/master.yml index 72d6335b..5e0fa432 100644 --- a/.github/workflows/master.yml +++ b/.github/workflows/master.yml @@ -22,7 +22,6 @@ jobs: python -m pip install --upgrade pipenv pip install pipenv pipenv install --dev - sudo gem install mdl - name: Start local DynamoDB run: scripts/download_dynamodb_and_run.sh - name: Test everything diff --git a/.github/workflows/pythonpackage.yml b/.github/workflows/pythonpackage.yml index a79195d2..c840f974 100644 --- a/.github/workflows/pythonpackage.yml +++ b/.github/workflows/pythonpackage.yml @@ -18,7 +18,6 @@ jobs: python -m pip install --upgrade pipenv pip install pipenv pipenv install --dev - sudo gem install mdl - name: Start local DynamoDB run: scripts/download_dynamodb_and_run.sh - name: Test everything diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 636e19db..b2b3c5d3 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -83,8 +83,6 @@ The Github build checks for: `pycodestyle `__) - Correctly-formatted docstrings (via `pydocstyle `__) -- Correctly-formatted Markdown documentation (via - `mdl `__) All of these checks are conveniently done using the ``scripts/build_check.sh`` as mentioned above. diff --git a/scripts/build_check.sh b/scripts/build_check.sh index 3b0ec922..39849901 100755 --- a/scripts/build_check.sh +++ b/scripts/build_check.sh @@ -7,7 +7,6 @@ pushd "${REPO_ROOT}" pipenv run pycodestyle . pipenv run flake8 . pipenv run mypy . -mdl . # We use a script to check if dynamodb is running locally COV_OPTIONS="--mypy --cov=./ --cov-branch --cov-config .coveragerc"