Skip to content

Commit

Permalink
Update docs to work with discussions (#395)
Browse files Browse the repository at this point in the history
  • Loading branch information
d-a-bunin authored Jun 20, 2024
1 parent 1ac5b97 commit 3736b02
Show file tree
Hide file tree
Showing 8 changed files with 120 additions and 39 deletions.
23 changes: 23 additions & 0 deletions .github/DISCUSSION_TEMPLATE/improvements.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
labels: ["improvement/idea", "improvement/drawback"]
body:
- type: textarea
attributes:
label: Description
description: |
Description of the suggested improvement.
validations:
required: true
- type: textarea
attributes:
label: Thoughts
description: |
Thoughts about the improvement: benefits, drawbacks, alternatives, possible implementations, etc.
validations:
required: false
- type: textarea
attributes:
label: Related
description: |
Related issues, pull requests, or other discussions.
validations:
required: false
4 changes: 2 additions & 2 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
name: "Bug report"
name: Bug report
title: "[BUG] "
description: If something isn't working as expected 🤔
labels: bug
Expand Down Expand Up @@ -43,7 +43,7 @@ body:
attributes:
label: Environment
description: |
OS, version of library, etc.
OS, version of Python, version of library, version of all Python packages, etc.
validations:
required: false

Expand Down
10 changes: 10 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
contact_links:
- name: Suggest an idea
about: Suggest an idea for the library using GitHub Discussions.
url: https://github.com/etna-team/etna/discussions/categories/improvements
- name: Point out a drawback
about: Describe a drawback of the library using GitHub Discussions.
url: https://github.com/etna-team/etna/discussions/categories/improvements
- name: Ask about usage
about: Ask about usage of the library using GitHub Discussions.
url: https://github.com/etna-team/etna/discussions/categories/q-a
23 changes: 23 additions & 0 deletions .github/ISSUE_TEMPLATE/docs_improvement.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
---
name: Documentation improvement
description: Make documentation better by suggesting an improvement or pointing out a problem
title: "[DOCS] "
labels: documentation

body:
- type: textarea
attributes:
label: 📖 Documentation improvement
description: |
A clear and concise description of the improvement or problem.
validations:
required: true

- type: textarea
attributes:
label: Additional context
description: |
Add any other context or screenshots about the issue here.
validations:
required: false
...
Original file line number Diff line number Diff line change
@@ -1,34 +1,33 @@
---
name: Feature request
description: Suggest an idea for this project
labels: enhancement
name: Task
description: Suggest a task for this project

body:
- type: textarea
attributes:
label: 🚀 Feature Request
description: A clear and concise description of the feature proposal (description of what result should look like).
label: 🚀 Task description
description: A clear and concise description of the task, what result should look like.
validations:
required: true

- type: textarea
attributes:
label: Proposal
description: A clear and concise description of what you want to happen. Ideally step by step with interface examples.
label: Plan
description: A clear description of what should be done in the task. Ideally step by step with interface examples.
validations:
required: true

- type: textarea
attributes:
label: Test cases
description: A description of test cases that should be added to test the feature.
description: A description of test cases that should be added / updated.
validations:
required: false

- type: textarea
attributes:
label: Additional context
description: Add any other context or screenshots about the feature request here.
description: Add any other context or screenshots about the task here.
validations:
required: false

Expand Down
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
-
-
-
-
- Update documentation to explain how to contribute and work with discussions, update templates for issues ([#395](https://github.com/etna-team/etna/pull/395))
-
-

Expand Down
69 changes: 43 additions & 26 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,38 @@
# Contribution guide

## How to start?

Contributing is quite easy: suggest ideas and make them done.
We use [GitHub issues](https://github.com/etna-team/etna/issues) for bug reports and feature requests.
Let's look at the possible ways to contribute to the project:
- Voting for suggestions
- Vote for the suggestion you are interested in on [GitHub Discussions](https://github.com/etna-team/etna/discussions/categories/improvements)
- Taking part in discussions
- Take part in discussions on [GitHub Discussions](https://github.com/etna-team/etna/discussions)
- Improving documentation
- Create an [issue about improving documentation](https://github.com/etna-team/etna/issues/new/choose)
- Sending bug report
- Create an [issue about bug](https://github.com/etna-team/etna/issues/new/choose)
- Suggesting an idea
- If there is suggestion with very similar idea on [GitHub Discussions](https://github.com/etna-team/etna/discussions/categories/improvements), vote for it
- Otherwise, add new idea to [GitHub Discussions](https://github.com/etna-team/etna/discussions/categories/improvements)
- You could continue this step by taking part in discussion
- Pointing out a problem
- If there is suggestion with very similar problem on [GitHub Discussions](https://github.com/etna-team/etna/discussions/categories/improvements), vote for it
- Otherwise, add new problem to [GitHub Discussions](https://github.com/etna-team/etna/discussions/categories/improvements)
- You could continue this step by taking part in discussion
- Making a pull request
- If there is a feature you want to add or bug you want to fix
- Follow a [step-by-step guide](##step-by-step-guide-for-making-a-pull-request)

## Step-by-step guide for making a pull request

Every good PR usually consists of:
- feature implementation :)
- documentation to describe this feature to other people
- tests to ensure everything is implemented correctly

## Step-by-step guide
- tests to ensure everything is implemented correctly.

### 1. Before the PR
Please ensure that you have read the following docs:
- [documentation](https://docs.etna.ai/stable/)
- [tutorials](https://github.com/etna-team/etna/tree/master/examples)
- [changelog](https://github.com/etna-team/etna/blob/master/CHANGELOG.md)
- [documentation](https://docs.etna.ai/stable/),
- [tutorials](https://github.com/etna-team/etna/tree/master/examples),
- [changelog](https://github.com/etna-team/etna/blob/master/CHANGELOG.md).

### 2. Setting up your development environment

Expand All @@ -37,22 +53,23 @@ poetry shell

To connect virtual environment interpreter to IDE the `which python` command can be useful.

### 3. Suggesting a feature (optional)

This is an optional step, you could skip it if you want to take some of the existing tasks.
### 3. Choosing a task

1. Make an issue with your feature description;
2. We shall discuss the design and its implementation details;
3. Once we agree that the plan looks good, go ahead and implement it.
Ready to do tasks are present at [GitHub Issues](https://github.com/etna-team/etna/issues):
- Pick an issue with status "Todo" on a [board](https://github.com/orgs/etna-team/projects/1);
- Pay attention for the label "good first issue" if you are new to the project.

### 4. Choosing a task
If there aren't interesting tasks go to [GitHub Discussions with improvements](https://github.com/etna-team/etna/discussions/categories/improvements):
1. Pick an improvement you want to work with;
2. Leave a comment in the discussion that you want to work on this;
3. Take part in discussion about the implementation details;
4. Wait for the issue to be created based on this discussion.

1. Goto [GitHub issues](https://github.com/etna-team/etna/issues);
2. Pick an issue with status "Todo" on a [board](https://github.com/orgs/etna-team/projects/1)
3. Leave a comment in the issue that you want to work on this task;
4. If you need more context on a specific issue, please ask, and we will discuss the details.
After you picked your issue to work with:
1. Leave a comment in the issue that you want to work on this task;
2. If you need more context on a specific issue, please ask, and we will discuss the details.

### 5. Doing a task
### 4. Doing a task

You can also join our [ETNA Community telegram chat](https://t.me/etna_support) to make it easier to discuss.
Once you finish implementing a feature or bugfix, please send a Pull Request.
Expand All @@ -61,7 +78,7 @@ If you are not familiar with creating a Pull Request, here are some guides:
- [Creating a pull request](https://help.github.com/articles/creating-a-pull-request/);
- [Creating a pull request from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).

### 6. Writing tests
### 5. Writing tests

Do not forget to check that your code passes the unit tests.
```bash
Expand All @@ -77,7 +94,7 @@ make format

If any of checks fails, the CI will fail and your Pull Request won't be merged.

### 7. Writing a documentation
### 6. Writing a documentation

If you update the code, the documentation should be updated accordingly.
ETNA uses [Numpydoc style](https://numpydoc.readthedocs.io/en/latest/format.html) for formatting docstrings.
Expand Down Expand Up @@ -105,7 +122,7 @@ Useful links:
The simplest way to check how documentation is rendered is to make a pull request.
CI will build it, publish and attach a link to the pull request.

#### 7.1 Standard scenarios
#### 6.1 Standard scenarios

**Adding a new method to the class**
- Update the docstrings of the class / method.
Expand Down Expand Up @@ -135,7 +152,7 @@ CI will build it, publish and attach a link to the pull request.
- Create a new page in a [`source`](https://github.com/etna-team/etna/tree/master/docs/source) directory.
- Add a link to the new page to [`user_guide.rst`](https://github.com/etna-team/etna/blob/master/docs/source/user_guide.rst) or any other page responsible for the documentation sections.

#### 7.2 Building locally (optional)
#### 6.2 Building locally (optional)

You can also build the documentation locally.
Before building the documentation you may need to install a pandoc package ([pandoc installation guide](https://pandoc.org/installing.html)):
Expand Down
11 changes: 10 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,16 @@ ETNA documentation is available [here](https://docs.etna.ai/stable/).

## Community

To ask the questions or discuss the library you can join our [telegram chat](https://t.me/etna_support).
Questions and feedback are welcome! Our channels for communication:
- [Discussions](https://github.com/etna-team/etna/discussions)
- Suggestions with ideas and drawbacks
- Q&A, e.g. usage questions
- General discussions
- [Issue tracker](https://github.com/etna-team/etna/issues)
- Bug reports
- Tasks
- [Telegram chat](https://t.me/etna_support)
- Useful for any other form of communication

## Resources

Expand Down

0 comments on commit 3736b02

Please sign in to comment.