Skip to content

Commit

Permalink
Re-organize docs + start using "Keep a Changelog" style (#689)
Browse files Browse the repository at this point in the history 
* doc reorg + apply "keep a changelog" style to changelog.rst

* fix spelling mistakes

* minor improvements

* remove unused ref

* fix typos
  • Loading branch information
@rmorshea
rmorshea authored Feb 27, 2022
1 parent 2a54b34 commit 3f8803e
Show file tree
Hide file tree
Showing 132 changed files with 219 additions and 426 deletions.
56 changes: 43 additions & 13 deletions docs/source/developing-idom/changelog.rst → docs/source/about/changelog.rst
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,41 @@
Changelog
=========

The IDOM team manages their short and long term plans with `GitHub Projects
<https://github.com/orgs/idom-team/projects/1>`__. If you have questions about what the
team are working on, or have feedback on how issues should be prioritized, feel free to
:discussion-type:`open up a discussion <question>`.
.. note::

The IDOM team manages their short and long term plans with `GitHub Projects
<https://github.com/orgs/idom-team/projects/1>`__. If you have questions about what
the team are working on, or have feedback on how issues should be prioritized, feel
free to :discussion-type:`open up a discussion <question>`.

All notable changes to this project will be recorded in this document. The style of
which is based on `Keep a Changelog <https://keepachangelog.com/>`__. The versioning
scheme for the project adheres to `Semantic Versioning <https://semver.org/>`__.


Unreleased
----------

While this release doesn't warrant a minor version bump, the last release should have
been. Thus, to make up for that, this release will be a minor bump. It includes misc
bug fixes, and several feature adds, the most important of which is the addition of the
``use_context`` hook.

Added:

- Support for keys in HTML fragments - :issue:`682`

**Merged Pull Requests**

- reset schedule_render_later flag after triggering - :pull:`688`
- support keys in HTML fragments - :pull:`683`
- Add Use Context Hook - :pull:`585`

----

Releases below do not use the "Keep a Changelog" style guidelines.

----

0.36.3
------
Expand Down Expand Up @@ -92,7 +122,7 @@ for elements at the root did not trigger unmounts.
------

As part of :pull:`614`, elements which changed type were not deeply unmounted. This
behavior is probably undesireable though since the state for children of the element
behavior is probably undesirable though since the state for children of the element
in question would persist (probably unexpectedly).

**Pull Requests**
Expand Down Expand Up @@ -136,7 +166,7 @@ this marker file.
The highlight of this release is that the default :ref:`"key" <Organizing Items With
Keys>` of all elements will be their index amongst their neighbors. Previously this
behavior could be engaged by setting ``IDOM_FEATURE_INDEX_AS_DEFAULT_KEY=1`` when
running IDOM. In this release though, you will need to explicitely turn off this feature
running IDOM. In this release though, you will need to explicitly turn off this feature
(i.e. ``=0``) to return to the old behavior. With this change, some may notice
additional error logs which warn that:

Expand Down Expand Up @@ -200,7 +230,7 @@ event dictionary. As part of this change we also add ``event["currentTarget"]``
0.33.3
------

Contains a small number of bug fixes and improvements. The most signicifact change is
Contains a small number of bug fixes and improvements. The most significant change is
the addition of a warning stating that `IDOM_FEATURE_INDEX_AS_DEFAULT_KEY=1` will become
the default in a future release. Beyond that, a lesser improvement makes it possible to
use the default export from a Javascript module when calling `module_from_template` by
Expand Down Expand Up @@ -277,7 +307,7 @@ yet.

- move VdomDict and VdomJson to proto - :pull:`492`
- only send error info in debug mode - :pull:`491`
- correcly apply client-side JSON patch - :pull:`490`
- correctly apply client-side JSON patch - :pull:`490`
- add script to set version of all packages in IDOM - :pull:`483`
- Pass import source to bind - :pull:`482`
- Do not mutate client-side model - :pull:`481`
Expand Down Expand Up @@ -339,12 +369,12 @@ The latter behavior is the most egregious design issue since there's absolutely
indication that the component instance can be swapped out (not even a comment).

The new refactor no longer binds component or layout instances to a ``LifeCycleHook``.
Instead, the hook simply receives an unparametrized callback that can be triggered to
Instead, the hook simply receives an un-parametrized callback that can be triggered to
schedule a render. While some error logs lose clarity (since we can't say what component
caused them). This change precludes a need for the layout to ever mutate the hook.

To accomodate this change, the internal representation of the layout's state had to
change. Previsouly, a class-based approach was take, where methods of the state-holding
To accommodate this change, the internal representation of the layout's state had to
change. Previously, a class-based approach was take, where methods of the state-holding
classes were meant to handle all use cases. Now we rely much more heavily on very simple
(and mostly static) data structures that have purpose built constructor functions that
much more narrowly address each use case.
Expand Down Expand Up @@ -497,7 +527,7 @@ and breaking changes, the most significant of which are:
- refactor flask - :commit:`94681b6`
- refactor tornado + misc fixes to sanic/fastapi - :commit:`16c9209`
- refactor fastapi using server protocol - :commit:`0cc03ba`
- recactor sanic server - :commit:`43d4b4f`
- refactor sanic server - :commit:`43d4b4f`
- use server protocol instead of inheritance - :commit:`abe0fde`
- support currentTime attr of audio/video elements - :commit:`975b54a`
- pass children as props to mount() - :commit:`9494bc0`
Expand Down Expand Up @@ -554,7 +584,7 @@ several bugs that had cropped up related to improper usage of ``anyio``.

**Highlighted Commits:**

- improve docs + simplify multiview - :commit:`4129b60`
- improve docs + simplify multi-view - :commit:`4129b60`
- require anyio>=3.0 - :commit:`24aed28`
- refactor dispatchers - :commit:`ce8e060`

Expand Down
188 changes: 89 additions & 99 deletions ...rce/developing-idom/contributor-guide.rst → docs/source/about/contributor-guide.rst
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,42 @@
Contributor Guide
=================

.. note::

The
`Code of Conduct <https://github.com/idom-team/idom/blob/main/CODE_OF_CONDUCT.md>`__
applies in all community spaces. If you are not familiar with our Code of Conduct
policy, take a minute to read it before making your first contribution.

The IDOM team welcomes contributions and contributors of all kinds - whether they come
as code changes, participation in the discussions, opening issues and pointing out bugs,
or simply sharing your work with your colleagues and friends. We're excited to see how
you can help move this project and community forward!


.. _everyone can contribute:

Everyone Can Contribute!
------------------------

Trust us, there's so many ways to support the project. We're always looking for people
who can:

- Improve our documentation
- Teach and tell others about IDOM
- Share ideas for new features
- Report bugs
- Participate in general discussions

Still aren't sure what you have to offer? Just :discussion-type:`ask us <question>` and
we'll help you make your first contribution.


.. note::

If you have any questions during set up or development post on our
:discussion-type:`discussion board <question>` and we'll answer them.

This project uses the `GitHub Flow`_ (more detail :ref:`below <Making a Pull Request>`)
for collaboration and consists primarily of Python code and Javascript code. A
:ref:`variety of tools <Development Environment>` are used to aid in its development.
Any code contributed to IDOM is validated by a :ref:`series of tests <Running The
Tests>` to ensure its quality and correctness.


Making a Pull Request
---------------------
Expand Down Expand Up @@ -41,6 +66,47 @@ about how to get started. To make a change to IDOM you'll do the following:
:ref:`equality checks <Code Quality Checks>` and, with any luck, accept your request.
At that point your contribution will be merged into the main codebase!

Create a Changelog Entry
........................

As part of your pull request, you'll want to edit the :ref:`Changelog` by adding an
entry describing what you've changed or improved. You should write an entry in the style
of `Keep a Changelog <https://keepachangelog.com/>`__ that falls under one of the
following categories, and add it to the :ref:`Unreleased` section of the changelog:

- **Added** - for new features.
- **Changed** - for changes in existing functionality.
- **Deprecated** - for soon-to-be removed features.
- **Removed** - for now removed features.
- **Fixed** - for any bug fixes.
- **Documented** - for improvements to this documentation.
- **Security** - in case of vulnerabilities.

If one of the sections doesn't exist, add it. If it does already, add a bullet point
under the relevant section. Here's a short example of what an unreleased changelog entry
might look like:

.. code-block:: rst
Unreleased
----------
**Added**
- A really cool new feature - :pull:`123`
**Changed**
- The behavior of some existing feature - :pull:`456`
**Fixed**
- Some really bad bug - :issue:`789`
.. note::

``:issue:`` and ``:pull:`` refer to issue and pull request ticket numbers.


Development Environment
-----------------------
Expand Down Expand Up @@ -104,19 +170,15 @@ However you may also ``cd`` to the ``src/client`` directory which contains a
Running The Tests
-----------------

The test suite for IDOM uses Nox_ and NPM_ in order to validate:
The test suite for IDOM is executed with Nox_. The suite covers:

1. Server-side Python code with PyTest_

2. The end-to-end application using Selenium_ in Python

3. Client-side Javascript code with UVU_


Running Python Tests
....................

To run the full suite of Python tests you'll need to install:
To run the full suite of tests you'll need to install:

- `Google Chrome`_

Expand All @@ -126,8 +188,7 @@ To run the full suite of Python tests you'll need to install:

Be sure the version of `Google Chrome`_ and ChromeDriver_ you install are compatible.

Once you've installed the aforementioned browser and web driver you should be able to
run:
Once you've installed the aforementioned browser and web driver you'll be able to run:

.. code-block:: bash
Expand All @@ -139,27 +200,6 @@ If you prefer to run the tests using a headless browser:
nox -s test -- --headless
You can pass other options to pytest in a similar manner:

.. code-block:: bash
nox -s test -- arg --flag --key=value
Running Javascript Tests
........................

If you've already run ``npm install`` inside the ``src/idom/client/app`` directory, you
can execute the suite of workspace tests under ``packages/*`` with:

.. code-block::
npm test
As a final check, you might want to run ``npm run build``. This command is run in the
top-level ``setup.py`` installation script for the Python package, so if this command
fails, the installation of the Python package with ``pip`` will too.

Code Quality Checks
-------------------
Expand All @@ -175,11 +215,12 @@ The following are currently being used:
- Black_ - an opinionated code formatter
- Flake8_ - a style guide enforcement tool
- ISort_ - a utility for alphabetically sorting imports
- Prettier_ - a tool for autimatically formatting Javascript code
- Prettier_ - a tool for automatically formatting various file types

The most strict measure of quality enforced on the codebase is 100% coverage. This means
that every line of coded added to IDOM requires a test case that exercises it. This
doesn't prevent all bugs, but it should ensure that we catch the most common ones.
The most strict measure of quality enforced on the codebase is 100% test coverage in
Python files. This means that every line of coded added to IDOM requires a test case
that exercises it. This doesn't prevent all bugs, but it should ensure that we catch the
most common ones.

If you need help understanding why code you've submitted does not pass these checks,
then be sure to ask, either in the :discussion-type:`Community Forum <question>` or in
Expand All @@ -196,7 +237,7 @@ your :ref:`Pull Request <Making a Pull Request>`.
Building The Documentation
--------------------------

To build and display the documentation simply run:
To build and display the documentation locally run:

.. code-block:: bash
Expand All @@ -215,13 +256,13 @@ To run some of the examples in the documentation as if they were tests run:
nox -s test_docs
Building the documentation as it's deployed in production requires Docker_. Once you've
installed, you can run:
installed Docker, you can run:

.. code-block:: bash
nox -s docs_in_docker
You should then navigate to to see the documentation.
Where you can then navigate to http://localhost:5000..


Release Process
Expand Down Expand Up @@ -249,58 +290,7 @@ To update the version for all core Javascript and Python packages in IDOM run:
.. note::

The new version must adhere to `SemVer <https://semver.org/>`__. Once IDOM
becomes stable we will shift to using `CalVer <https://calver.org/>`__.


Create Changelog Entry
......................

Immediately after updating the version you'll need to create a changelog entry for the
release. This should **always** include a human authored summary of the changes it
includes. For example, new or deprecated features, performance improvements, and bug
fixes (whatever is relevant). To help with this, there are some useful tools for
gathering the Pull Requests and Issues that have been merged and resolved since the last
release. While reviewing these items can help in writing a human authored release
summary, you **must not** resort to a bullet list of Pull Request and Issue
descriptions. Putting these two together, the format of a changelog entry should look a
bit like this:

.. code-block:: text
X.Y.Z
-----
The release summary...
**Closed Issues**
- Some issue - :issue:`123`
- Another issue - :issue:`456`
**Pull Requests**
- Some pull request - :pull:`123`
- Another pull request - :pull:`456`
**Deprecated Features**
- Description one
- Description two
To create the list of pull requests and closed issues you can copy the output of the
following commands using the ``<format>`` of your choosing (``rst``, ``md``, ``text``):

.. note::

You should currate the list - not everything needs to be included.

.. code-block:: bash
nox -s changes_since_release -- <format>
Once the version has been updated and the changelog entry completed, you should commit
the changes.
The new version must adhere to `SemVer <https://semver.org/>`__.


Creating The Release
Expand All @@ -321,12 +311,12 @@ To create the release tag you can run the following command:
nox -s tag -- push
Last, you must create a
`"Release" <https://docs.github.com/en/github/administering-a-repository/releasing-projects-on-github/managing-releases-in-a-repository>`__
Last, you must create a `"Release"
<https://docs.github.com/en/github/administering-a-repository/releasing-projects-on-github/managing-releases-in-a-repository>`__
in GitHub. Because we pushed a tag using the command above, there should already be a
saved draft which needs a title and desription. The title should simply be the version
(same as the tag), and the description should, at minimum, be a markdown version of the
already authored :ref:`Changelog summary <Create Changelog Entry>`.
saved draft which needs a title and description. The title should simply be the version
(same as the tag), and the description should simply use GitHub's "Auto-generated
release notes".


Other Core Repositories
Expand Down
2 changes: 1 addition & 1 deletion docs/source/credits-and-licenses.rst → docs/source/about/credits-and-licenses.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,5 +12,5 @@ copy language or examples where IDOM's behavior mirrors that of React's.
Source Code License
-------------------

.. literalinclude:: ../../LICENSE
.. literalinclude:: ../../../LICENSE
:language: text
Loading

0 comments on commit 3f8803e

Please sign in to comment.