diff --git a/docs/contributing.md b/docs/contributing.md index 9ceabb1..5a6af0a 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,7 +1,7 @@ # Contributing -Contributions are welcome, and they are greatly appreciated! Every -little bit helps, and credit will always be given. +Contributions are welcome, and they are greatly appreciated! Every little bit +helps, and credit will always be given. You can contribute in many ways: @@ -13,27 +13,24 @@ Report bugs at https://github.com/osl-incubator/makim.git/issues. If you are reporting a bug, please include: - - Your operating system name and version. - - Any details about your local setup that might be helpful in - troubleshooting. - - Detailed steps to reproduce the bug. +- Your operating system name and version. +- Any details about your local setup that might be helpful in troubleshooting. +- Detailed steps to reproduce the bug. ### Fix Bugs -Look through the GitHub issues for bugs. Anything tagged with “bug” and -“help wanted” is open to whoever wants to implement it. +Look through the GitHub issues for bugs. Anything tagged with “bug” and “help +wanted” is open to whoever wants to implement it. ### Implement Features -Look through the GitHub issues for features. Anything tagged with -“enhancement” and “help wanted” is open to whoever wants to implement -it. +Look through the GitHub issues for features. Anything tagged with “enhancement” +and “help wanted” is open to whoever wants to implement it. ### Write Documentation -makim could always use more documentation, -whether as part of the official makim docs, -in docstrings, or even on the web in blog posts, articles, and such. +makim could always use more documentation, whether as part of the official makim +docs, in docstrings, or even on the web in blog posts, articles, and such. ### Submit Feedback @@ -42,59 +39,73 @@ https://github.com/osl-incubator/makim.git/issues. If you are proposing a feature: - - Explain in detail how it would work. - - Keep the scope as narrow as possible, to make it easier to - implement. - - Remember that this is a volunteer-driven project, and that - contributions are welcome :) +- Explain in detail how it would work. +- Keep the scope as narrow as possible, to make it easier to implement. +- Remember that this is a volunteer-driven project, and that contributions are + welcome :) ## Get Started! -For development, we encourage you to use `conda`. If you don't know -what is that, check these links: +For development, we encourage you to use `conda`. If you don't know what is +that, check these links: -* In Spanish: https://opensciencelabs.org/blog/como-instalar-y-comenzar-utilizar-conda/ -* In English: https://cloudsmith.com/blog/what-is-conda/ +- In Spanish: + https://opensciencelabs.org/blog/como-instalar-y-comenzar-utilizar-conda/ +- In English: https://cloudsmith.com/blog/what-is-conda/ -We recommend you to use mamba-forge, a combination of -miniconda + conda-forge + mamba. You can download it from here: +We recommend you to use mamba-forge, a combination of miniconda + conda-forge + +mamba. You can download it from here: https://github.com/conda-forge/miniforge#mambaforge Ready to contribute? Here’s how to set up `makim` for local development. 1. Fork the `makim` repo on GitHub. 2. Clone your fork locally: + ```bash $ git clone git@github.com:your_name_here/makim.git ``` + 3. Create a conda environment and activate it: + ```bash $ mamba env create --file conda/dev.yaml ``` + and + ```bash $ conda activate makim ``` + 4. Install your local project copy into your conda environment: + ```bash $ poetry install ``` + 5. Create a branch for local development:: + ```bash $ git checkout -b name-of-your-bugfix-or-feature ``` -6. When you’re done makimg changes, check that your changes pass flake8 - and the tests, including testing other Python versions with tox:: + +6. When you’re done makimg changes, check that your changes pass flake8 and the + tests, including testing other Python versions with tox:: + ```bash $ makim tests.linter $ makim tests.unittest $ makim tests.smoke ``` + 7. Commit your changes and push your branch to GitHub:: + ```bash $ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature ``` + 8. Submit a pull request through the GitHub website. ## Pull Request Guidelines @@ -102,9 +113,9 @@ $ git push origin name-of-your-bugfix-or-feature Before you submit a pull request, check that it meets these guidelines: 1. The pull request should include tests. -2. If the pull request adds functionality, the docs should be updated. - Put your new functionality into a function with a docstring, and add - the feature to the list in README.rst. +2. If the pull request adds functionality, the docs should be updated. Put your + new functionality into a function with a docstring, and add the feature to + the list in README.rst. 3. The pull request should work for Python >= 3.8. ## Tips @@ -117,42 +128,42 @@ $ pytest tests.test_containers_sugar ## Release -This project uses semantic-release in order to cut a new release -based on the commit-message. +This project uses semantic-release in order to cut a new release based on the +commit-message. ### Commit message format -**semantic-release** uses the commit messages to determine the consumer -impact of changes in the codebase. Following formalized conventions for -commit messages, **semantic-release** automatically determines the next +**semantic-release** uses the commit messages to determine the consumer impact +of changes in the codebase. Following formalized conventions for commit +messages, **semantic-release** automatically determines the next [semantic version](https://semver.org) number, generates a changelog and publishes the release. -By default, **semantic-release** uses [Angular Commit Message -Conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format). -The commit message format can be changed with the `preset` or `config` -options_ of the +By default, **semantic-release** uses +[Angular Commit Message Conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format). +The commit message format can be changed with the `preset` or `config` options\_ +of the [@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer#options) and [@semantic-release/release-notes-generator](https://github.com/semantic-release/release-notes-generator#options) plugins. Tools such as [commitizen](https://github.com/commitizen/cz-cli) or -[commitlint](https://github.com/conventional-changelog/commitlint) can -be used to help contributors and enforce valid commit messages. +[commitlint](https://github.com/conventional-changelog/commitlint) can be used +to help contributors and enforce valid commit messages. -The table below shows which commit message gets you which release type -when `semantic-release` runs (using the default configuration): +The table below shows which commit message gets you which release type when +`semantic-release` runs (using the default configuration): | Commit message | Release type | -|----------------------------------------------------------------|------------------| +| -------------------------------------------------------------- | ---------------- | | `fix(pencil): stop graphite breaking when pressure is applied` | Fix Release | | `feat(pencil): add 'graphiteWidth' option` | Feature Release | | `perf(pencil): remove graphiteWidth option` | Chore | -| `BREAKING CHANGE: The graphiteWidth option has been removed` | Breaking Release | +| `feat(pencil)!: The graphiteWidth option has been removed` | Breaking Release | source: -As this project uses the `squash and merge` strategy, ensure to apply -the commit message format to the PR's title. +As this project uses the `squash and merge` strategy, ensure to apply the commit +message format to the PR's title. diff --git a/docs/installation.md b/docs/installation.md index 40a0b48..9fc9d48 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -14,13 +14,13 @@ Makim is also available on conda-forge: $ conda install -c conda-forge makim ``` -This is the preferred method to install makim, -as it will always install the most recent stable release. +This is the preferred method to install makim, as it will always install the +most recent stable release. ## From sources -The sources for makim can be downloaded from -the [Github repo](https://github.com/osl-incubator/makim.git). +The sources for makim can be downloaded from the +[Github repo](https://github.com/osl-incubator/makim.git). You can either clone the public repository: @@ -35,8 +35,8 @@ Or download the $ curl -OJL https://github.com/osl-incubator/makim.git/tarball/main ``` -Once you have a copy of the source, change to the project root directory -and install it with: +Once you have a copy of the source, change to the project root directory and +install it with: ```bash $ poetry install diff --git a/docs/xonsh.md b/docs/xonsh.md new file mode 100644 index 0000000..c2ba339 --- /dev/null +++ b/docs/xonsh.md @@ -0,0 +1,60 @@ +# Xonsh Shell Integration + +In the context of this project, Xonsh serves as the default shell for executing +commands defined in the Makim configuration. By leveraging Xonsh, the Makim tool +gains the flexibility and richness of the Python programming language within a +command-line interface. This integration allows users to create sophisticated +tasks and harness the full power of Python directly in the terminal. + +## What is Xonsh? + +[Xonsh](https://xon.sh/) is a powerful shell language and command prompt +designed to seamlessly blend traditional shell capabilities with the expressive +syntax of Python. It offers an interactive and extensible environment that +enables users to transition effortlessly between standard shell commands and +Python scripting. + +## Key Features and Commands in Xonsh + +1. **Unified Syntax :** Xonsh seamlessly integrates traditional shell syntax + with Python's clean and expressive syntax, creating a unified and consistent + scripting experience. + +``` +# Shell-style command +ls -l +# Python-style variable assignment +$filename = "example.txt" +# Combining both in a single command +echo "The contents of $filename are: $(cat $filename)" +``` + +2. **Python Variables and Expressions :** Python variables can be easily + incorporated into commands, enhancing the readability and flexibility of your + scripts. + +``` +$filename = "example.txt" +echo "The filename is $filename" +``` + +3. **Looping and Conditional Statements :** Use Python-style loops and + conditionals to create dynamic and complex command sequences. + +``` +for $i in range(3): + echo "Iteration $i" +``` + +4. **Extensible Tab Completion :** Xonsh offers extensible and intelligent tab + completion, making it easier to discover and complete commands and variables. + +``` +$long_variable_name = "some_value" +echo $long_ +# Xonsh will intelligently complete the variable name +``` + +For more comprehensive information and documentation, explore the [Xonsh GitHub +repository] (https://github.com/xonsh/xonsh) and the official +[Xonsh website](https://xon.sh/).