Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add more information to contributing page #7916

Merged
merged 42 commits into from Jan 28, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
42 commits
Select commit Hold shift + click to select a range
d155e00
Add more information to contributing page.
Dreamsorcerer Nov 27, 2023
1abf034
Create 7916.doc
Dreamsorcerer Nov 27, 2023
616576b
Update docs/contributing.rst
Dreamsorcerer Nov 27, 2023
1b67ffa
Update contributing.rst
Dreamsorcerer Nov 27, 2023
4677136
Update 7916.doc
Dreamsorcerer Nov 27, 2023
37a5a3a
Update spelling_wordlist.txt
Dreamsorcerer Nov 27, 2023
d4f956b
Update docs/contributing.rst
Dreamsorcerer Dec 1, 2023
aa58588
Include changes readme
Dreamsorcerer Dec 12, 2023
a2a6ed9
Update README.rst
Dreamsorcerer Dec 12, 2023
c8d8887
Update contributing.rst
Dreamsorcerer Dec 12, 2023
d625b3d
Update spelling_wordlist.txt
Dreamsorcerer Dec 12, 2023
8c3d928
Update contributing.rst
Dreamsorcerer Dec 12, 2023
14acacf
Update README.rst
Dreamsorcerer Dec 12, 2023
c761044
Update README.rst
Dreamsorcerer Dec 12, 2023
7639249
Update README.rst
Dreamsorcerer Dec 12, 2023
91ac91c
Update README.rst
Dreamsorcerer Dec 12, 2023
cb62097
Update CHANGES/7916.doc
Dreamsorcerer Jan 26, 2024
9089797
Update README.rst
Dreamsorcerer Jan 27, 2024
d96b18b
Update contributing.rst
Dreamsorcerer Jan 27, 2024
96b5c39
Create contributing-cov-comment.svg
Dreamsorcerer Jan 27, 2024
a733f0d
Update contributing.rst
Dreamsorcerer Jan 27, 2024
19efe3a
Delete docs/contributing-cov-comment.png
Dreamsorcerer Jan 27, 2024
1c2624b
Create contributing-cov-header.svg
Dreamsorcerer Jan 27, 2024
a2104ba
Update contributing.rst
Dreamsorcerer Jan 27, 2024
8760165
Delete docs/contributing-cov-header.png
Dreamsorcerer Jan 27, 2024
a2123d0
Update contributing.rst
Dreamsorcerer Jan 27, 2024
fe93ad4
Update contributing.rst
Dreamsorcerer Jan 27, 2024
d82e65e
Update README.rst
Dreamsorcerer Jan 27, 2024
7fe88d2
Update docs/contributing.rst
Dreamsorcerer Jan 28, 2024
2c5ab46
Header
Dreamsorcerer Jan 28, 2024
0aadbf2
Update contributing.rst
Dreamsorcerer Jan 28, 2024
1cbad49
Code coverage
Dreamsorcerer Jan 28, 2024
1bc8110
Update 7916.doc
Dreamsorcerer Jan 28, 2024
f4b72b2
.rst
Dreamsorcerer Jan 28, 2024
11fa848
Tip
Dreamsorcerer Jan 28, 2024
d8472a2
Create contributing-cov-partial.svg
Dreamsorcerer Jan 28, 2024
624905c
Create contributing-cov-miss.svg
Dreamsorcerer Jan 28, 2024
191b4c5
Delete docs/contributing-cov-miss.png
Dreamsorcerer Jan 28, 2024
aeb4018
Delete docs/contributing-cov-partial.png
Dreamsorcerer Jan 28, 2024
8284d87
Update contributing.rst
Dreamsorcerer Jan 28, 2024
1310a6d
Merge branch 'master' into docs-contributing
Dreamsorcerer Jan 28, 2024
c949f75
Update docs/contributing.rst
Dreamsorcerer Jan 28, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGES/7916.doc
@@ -0,0 +1 @@
Updated :ref:`contributing/Tests coverage <aiohttp-contributing>` section to show how we use ``codecov`` -- by :user:`Dreamsorcerer`.
29 changes: 20 additions & 9 deletions CHANGES/README.rst
@@ -1,15 +1,23 @@
.. _Adding change notes with your PRs:
.. _Making a pull request:

Making a pull request
=====================
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Dreamsorcerer this title was a mistake:

  1. Since it's rendered on GitHub in a folder with change notes, on any branch, it shouldn't really mention the PR process that much — just the process for having the changelog.
  2. The Sphinx site now has 2 subsequent titles with the same name but different capitalization — https://docs.aiohttp.org/en/stable/contributing.html#making-a-pull-request and https://docs.aiohttp.org/en/stable/contributing.html#id2.


When making a pull request, please include a short summary of the changes
and a reference to any issue tickets that the PR is intended to solve.
All PRs with code changes should include tests. All changes should
include a changelog entry.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I missed that this now refers to tests that are not related to the https://github.com/aio-libs/aiohttp/tree/master/CHANGES#readme directory at all.


Adding change notes with your PRs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Dreamsorcerer marked this conversation as resolved.
Show resolved Hide resolved
---------------------------------

It is very important to maintain a log for news of how
updating to the new version of the software will affect
end-users. This is why we enforce collection of the change
fragment files in pull requests as per `Towncrier philosophy`_.

The idea is that when somebody makes a change, they must record
the bits that would affect end-users only including information
the bits that would affect end-users, only including information
that would be useful to them. Then, when the maintainers publish
a new release, they'll automatically use these records to compose
a change log for the respective version. It is important to
Expand All @@ -19,7 +27,7 @@ to the end-users most of the time. And so such details should be
recorded in the Git history rather than a changelog.

Alright! So how to add a news fragment?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
---------------------------------------
Dreamsorcerer marked this conversation as resolved.
Show resolved Hide resolved

``aiohttp`` uses `towncrier <https://pypi.org/project/towncrier/>`_
for changelog management.
Expand All @@ -34,11 +42,14 @@ for the users to understand what it means.
combined with others, it will be a part of the "news digest"
telling the readers **what changed** in a specific version of
the library *since the previous version*. You should also use
reStructuredText syntax for highlighting code (inline or block),
*reStructuredText* syntax for highlighting code (inline or block),
linking parts of the docs or external sites.
If you wish to sign your change, feel free to add ``-- by
:user:`github-username``` at the end (replace ``github-username``
with your own!).
However, you do not need to reference the issue or PR numbers here
as *towncrier* will automatically add a reference to all of the
affected issues when rendering the news file.
If you wish to sign your change, feel free to add
``-- by :user:`github-username``` at the end (replace
``github-username`` with your own!).

Finally, name your file following the convention that Towncrier
understands: it should start with the number of an issue or a
Expand Down Expand Up @@ -77,7 +88,7 @@ necessary to make a separate documentation fragment for documentation
changes accompanying the relevant code changes.

Examples for adding changelog entries to your Pull Requests
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-----------------------------------------------------------
Dreamsorcerer marked this conversation as resolved.
Show resolved Hide resolved

File :file:`CHANGES/6045.doc.1.rst`:

Expand Down
55 changes: 55 additions & 0 deletions docs/_static/img/contributing-cov-comment.svg
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
15 changes: 15 additions & 0 deletions docs/_static/img/contributing-cov-header.svg
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.