-
Notifications
You must be signed in to change notification settings - Fork 0
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
Update and extend design documents #274
Open
Nicoretti
wants to merge
3
commits into
main
Choose a base branch
from
doc/desing-doc-updates
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from 1 commit
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| Addendums and Updates | ||
| ===================== | ||
|
|
||
| Nox as Task Executor and Task Creation | ||
| -------------------------------------- | ||
|
|
||
| Why Nox Was Chosen | ||
| ~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| Nox was initially selected as our task executor due to several reasons: | ||
|
|
||
| * **No Additional Languages Required**: There was no need to introduce extra programming languages or binaries, simplifying the development process. | ||
| * **Python-based**: Being Python-based, Nox can be extended, understood by python devs and also can share code. | ||
| * **Simplicity**: Nox is relatively "small" in functionality which makes it somewhat simple to use. | ||
|
|
||
| Although today, other options like `invoke` could be consider or used as a replacement, Nox still is working for use even though there are some rough edges. | ||
|
|
||
| Naming of Tasks and Grouping | ||
| ---------------------------- | ||
|
|
||
| Task Grouping with Nox | ||
| ~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| Since Nox doesn't natively support task grouping like Invoke, we need a strategy to clearly distinguish commands. We will adopt a naming convention to indicate grouping within the CLI. | ||
|
|
||
| Groups will be separated using a :code:`:` (colon) because :code:`-` (dash) might already be used within task names. | ||
|
|
||
| Examples | ||
| ++++++++ | ||
|
|
||
| **Task Names:** | ||
|
|
||
| * :code:`docs:clean` | ||
| * :code:`docs:build` | ||
| * :code:`docs:open` | ||
|
|
||
|
|
||
| **CLI Execution:** :code:`nox -s docs:clean docs:build docs:open` | ||
|
|
||
| This approach helps in organizing tasks logically and makes it easier for developers to identify and execute related commands. | ||
|
|
||
| By following these guidelines, we ensure a structured and comprehensible task management system, facilitating smoother development and maintenance. |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| .. _design_documents: | ||
|
|
||
|
|
||
| :octicon:`repo` Desing Documents | ||
Nicoretti marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ================================ | ||
|
|
||
| .. toctree:: | ||
| :maxdepth: 2 | ||
|
|
||
| design | ||
| addendum | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -7,7 +7,7 @@ | |
| .. toctree:: | ||
| :maxdepth: 2 | ||
|
|
||
| ../design | ||
| ../design/index | ||
| development | ||
| plugins | ||
| modules/modules | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there a specific reason why you didn't simply add the new/additional design updates to the existing file
design.rst?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, I thought it might be clearer to understand the evolution. Additionally, it potentially removes the trap of reverting back to something we had previously tried because a new person might think it is a "better" solution, even though it was already tried/used for a while and evolved to the current state.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would prefer having the design in a single version, not reflecting the history.
Compare to implementation, test, and documentation which also AFAIK always only reflect the latest state.
However, anticipating future regressions in design, i.e. trying out an approach that already has been evaluated and discarded, is valuable in my eyes.
Would maybe a section Design Decisions make sense here? I think it's perfectly OK, to just describe there what already has been evaluated and discarded and why.