Skip to content

Commit

Permalink
Docs: update contribution guidelines and dev setup (#2270)
Browse files Browse the repository at this point in the history
  • Loading branch information
@lostella
lostella authored Sep 5, 2022
1 parent cf57f73 commit a442592
Show file tree
Hide file tree
Showing 3 changed files with 64 additions and 288 deletions.
59 changes: 11 additions & 48 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,10 @@ documentation, we greatly value feedback and contributions from our community.
Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
information to effectively respond to your bug report or contribution.


## Questions and discussion topics

Questions and discussion topics can be proposed using [discussions](https://github.com/awslabs/gluon-ts/discussions).


## Reporting Bugs/Feature Requests

We welcome you to use the GitHub [issue tracker](https://github.com/awslabs/gluon-ts/issues/new/choose) to report bugs or suggest features.
Expand All @@ -24,11 +22,11 @@ reported the issue. Please try to include as much information as you can. Detail
* Any modifications you've made relevant to the bug
* Anything unusual about your environment or deployment


## Contributing via Pull Requests

Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:

1. You are working against the latest source on the *dev* branch.
1. You are working against the latest source on the `dev` branch.
2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
3. You open an issue to discuss any significant work - we would hate for your time to be wasted.

Expand All @@ -44,61 +42,26 @@ To send us a pull request, please:
GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
[creating a pull request](https://help.github.com/articles/creating-a-pull-request/).

## Development setup

## Development setup and coding style

For development you need the requirements listed in all `requirements...txt` files.

We use [black](https://github.com/python/black) and mypy for style and
type checking. Any code changes that you contribute should pass these checks.

The easiest way to get set up for development is to run the following script:

```bash
# first fork the repo on github

# then clone your fork
git clone https://github.com/<your-github-username>/gluon-ts.git

# enter the cloned repo
cd gluon-ts

# run development setup
./dev_setup.sh

# install GluonTS from current source with shell dependencies
pip install -e ".[shell]"
```
Note that windows and other versions of linux (not mac versions) will require
something slightly different to initiate the `dev_setup.sh` script.

This will install all the requirements and also install a git hook that runs
all code checks when you commit. This also separates your workflow so that
pull-requests go through your forked repo and then into upstream if approved.

You may wish to familiarize yourself with forked repositories on github, for
more see:
https://help.github.com/en/articles/working-with-forks

To avoid conflicts with existing python installations you may want to setup
a virtual environment. For more on virtual environments in python see:
https://docs.python.org/3/tutorial/venv.html
for python virtual environments and
https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html
for conda virtual environments.
Please refer to the [documentation](https://ts.gluon.ai/dev/community/devsetup.html) on how to set up your development environment.

## Finding contributions to work on
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any ['help wanted'](https://github.com/awslabs/gluon-ts/labels/help%20wanted) issues is a great place to start.

Looking at the existing issues is a great way to find something to contribute on: issues labeled with
['good first issue'](https://github.com/awslabs/gluon-ts/labels/good%20first%20issue) or
['help wanted'](https://github.com/awslabs/gluon-ts/labels/help%20wanted)
are a great place to start.

## Code of Conduct

This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
[email protected] with any additional questions or comments.


## Security issue notifications
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.

If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.

## Licensing

Expand Down
190 changes: 1 addition & 189 deletions docs/community/contribute.rst
View file
Original file line number Diff line number Diff line change
@@ -1,189 +1 @@
Contribute
==========

GluonTS community welcomes contributions from anyone! Latest documentation can be found `here <https://ts.gluon.ai/dev/index.html>`__.

There are lots of opportunities for you to become our `contributors <https://github.com/awslabs/gluon-ts/blob/dev/contributor.rst>`__:

- Ask or answer questions on `GitHub issues <https://github.com/awslabs/gluon-ts/issues>`__.
- Propose ideas, or review proposed design ideas on `GitHub issues <https://github.com/awslabs/gluon-ts/issues>`__.
- Improve the `documentation <https://ts.gluon.ai/dev/index.html>`__.
- Contribute bug reports `GitHub issues <https://github.com/awslabs/gluon-ts/issues>`__.
- Write new `tutorials <https://github.com/awslabs/gluon-ts/tree/dev/docs/tutorials>`__.
- Most importantly, if you have an idea of how to contribute, then do it!

For a list of open starter tasks, check `good first issues <https://github.com/awslabs/gluon-ts/labels/good%20first%20issue>`__.

- `Make changes <#make-changes>`__

- `Contribute tutorials <#contribute-tutorials>`__

- `Contribute new Models <#contribute-new-model>`__

- `Git Workflow Howtos <#git-workflow-howtos>`__

- `How to submit pull request <#how-to-submit-pull-request>`__
- `How to resolve conflict with
dev <#how-to-resolve-conflict-with-dev>`__
- `How to combine multiple commits into
one <#how-to-combine-multiple-commits-into-one>`__
- `What is the consequence of force
push <#what-is-the-consequence-of-force-push>`__


Make changes
------------

Our package uses continuous integration and code coverage tools for verifying pull requests. Before
submitting, contributor should perform the following checks:

- `Lint (code style) check <https://github.com/awslabs/gluon-ts/blob/dev/ci/jenkins/build_steps.groovy>`__.
- `Py3 <https://github.com/awslabs/gluon-ts/blob/dev/ci/jenkins/Jenkinsfile_py3_cpu_unittest>`__ tests.


Contribute tutorials
--------------------

Our :doc:`tutorials <../tutorials/index>` are intended for people who
are interested in time series and want to get better familiarized on different parts in time series. In order for
people to easily understand the content, the code needs to be clean and readable, accompanied by
explanation with good writing.

See `existing tutorials <https://github.com/awslabs/gluon-ts/tree/dev/docs/tutorials>`__.

To make the review process easy, we adopt `notedown <https://github.com/aaren/notedown>`_ as the
tutorial format. Notedown notebooks are regular markdown files with code blocks that can be
converted into `Jupyter notebooks <http://jupyter.org/>`_.

We suggest you start the example with `Jupyter notebook <http://jupyter.org/>`_. When the content is ready, please:

- Clear the output cells in the jupyter notebook,
- `Install notedown <https://github.com/aaren/notedown>`_.
- Run `notedown input.ipynb --to markdown > output.md`
- Submit the `.md` file for review.

Notebook Guidelines:

- Less is better. Only show the code that needs people's attention.
- Have a block upfront about the key takeaway of the notebook.
- Explain the motivation of the notebook to guide readers. Add figures if they help.
- Try to have < 10 lines of code per block, < 100 lines of code per notebook.
- Hide uninteresting complex functions in .py and import them.
- Hide uninteresting model parameters. We can make some of them default parameters in model definition. Maybe out of 30 we just show 5 interesting ones and pass those to model constructor.
- Only import module instead of classes and functions (i.e. from gluonts import model and use model.get_model, instead of from gluonts.model import get_model)
- Make tutorials more engaging, interactive, prepare practice questions for people to try it out. For example, for embedding evaluation, we can ask questions to the audience like what's the most similar word to xxx.
- Make sure the notebook can be zoomed in and still render well. This helps accommodate different viewing devices.
- For low level APIs such as BeamSearch and Scorer, explain the API with examples so ppl know how to play with it / hack it.


Contribute Docs
---------------

Documentation is at least as important as code. Good documentation delivers the correct message clearly and concisely.
If you see any issue in the existing documentation, a patch to fix is most welcome! To locate the
code responsible for the doc, you may use "Edit on Github" in the top right corner, or the
"[source]" links after each API. Also, `git grep` works nicely for searching for a specific string.

Git Workflow Howtos
-------------------

How to submit pull request
~~~~~~~~~~~~~~~~~~~~~~~~~~

- Before submit, please rebase your code on the most recent version of
dev, you can do it by

.. code:: bash
git remote add upstream https://github.com/awslabs/gluon-ts
git fetch upstream
git rebase upstream/dev
- If you have multiple small commits, it might be good to merge them
together(use git rebase then squash) into more meaningful groups.
- Send the pull request!

- Fix the problems reported by automatic checks
- If you are contributing a new module or new function, add a test.

How to resolve conflict with dev
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- First rebase to most recent dev

.. code:: bash
# The first two steps can be skipped after you do it once.
git remote add upstream https://github.com/awslabs/gluon-ts
git fetch upstream
git rebase upstream/dev
- The git may show some conflicts it cannot merge, say
``conflicted.py``.

- Manually modify the file to resolve the conflict.
- After you resolved the conflict, mark it as resolved by

.. code:: bash
git add conflicted.py
- Then you can continue rebase by

.. code:: bash
git rebase --continue
- Finally push to your fork, you may need to force push here.

.. code:: bash
git push --force
How to combine multiple commits into one
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sometimes we want to combine multiple commits, especially when later
commits are only fixes to previous ones, to create a PR with set of
meaningful commits. You can do it by following steps. - Before doing so,
configure the default editor of git if you haven't done so before.

.. code:: bash
git config core.editor the-editor-you-like
- Assume we want to merge last 3 commits, type the following commands

.. code:: bash
git rebase -i HEAD~3
- It will pop up an text editor. Set the first commit as ``pick``, and
change later ones to ``squash``.
- After you saved the file, it will pop up another text editor to ask
you modify the combined commit message.
- Push the changes to your fork, you need to force push.

.. code:: bash
git push --force
Reset to the most recent dev
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can always use git reset to reset your version to the most recent
dev. Note that all your ***local changes will get lost***. So only do
it when you do not have local changes or when your pull request just get
merged.

.. code:: bash
git reset --hard [hash tag of dev]
git push --force
What is the consequence of force push
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The previous two tips requires force push, this is because we altered
the path of the commits. It is fine to force push to your own fork, as
long as the commits changed are only yours.
.. mdinclude:: ../../CONTRIBUTING.md
Loading

0 comments on commit a442592

Please sign in to comment.