From 94b068191f7758c7c63180c5d9fb30e89d280fb6 Mon Sep 17 00:00:00 2001 From: Aarush Bhat Date: Thu, 11 Jan 2024 15:59:25 +0530 Subject: [PATCH] Documentation revamp (#49) * add readme for decision docs * more detailed readme * fix contributing.md * add intro to contributing md * add github contributing guidelines * change emoji * add how to reach out * move reach out, suggestions and questions to readme * add information about decision docs and primitives in contributing.md * add information about how to add tests blog --- contributing.md | 99 +++++++++++++++++++++++++++++++++++++++++ docs/decision/readme.md | 3 ++ readme.md | 24 +++++++--- 3 files changed, 121 insertions(+), 5 deletions(-) create mode 100644 contributing.md create mode 100644 docs/decision/readme.md diff --git a/contributing.md b/contributing.md new file mode 100644 index 0000000..f3ac288 --- /dev/null +++ b/contributing.md @@ -0,0 +1,99 @@ +# Contributing Guide + +We welcome contributions from anyone, even if you are new to open source. We will help you with any technical issues and help improve your contribution so that it can be merged. + +Every small change of refactoring, documentation, code commenting, questions, suggestions, adding a test, adding a primitive makes the project better and will help making Dyalog APL bug free. 𓆣 + +## Basic Setup + +To contribute, make sure your set up: + +- Your username + email +- Your ~/.gitconfig +- Dyalog (preferably version >18.2 unicode) + +### Fork ullu + +Step 1. Create a fork of the project repository + +Step 2. Clone the project repository from GitHub and set up your remote repository + +``` +git clone https://github.com/dyalog/ullu.git +cd ullu +git remote add REMOTE_NAME https://github.com/YOUR_GITHUB_USERNAME/ullu.git +``` + +`REMOTE_NAME` is the name of your remote repository and could be any name you like, for example your first name. + +`YOUR_GITHUB_USERNAME` is your user name on GitHub and should be part of your account path. + +You can use `git remote -v` to check if the new remote is set up correctly. + +## Sending a Pull Request/Merge Request + +Step 1. Create a new branch + +``` +git checkout -b fix1 +``` + +Step 2. Make changes in relevant file(s) +Step 3. Commit the changes: + +``` +git add FILE1 (FILE2 ...) +git commit -m "YOUR_COMMIT_MESSAGE" +``` + +[Here](https://cbea.ms/git-commit/) are some great tips on writing good commit messages. + +Step 4. Check to ensure that your changes look good +``` +git log --pretty=oneline --graph --decorate --all +``` + +Step 5. Send the pull request +``` +git push REMOTE_NAME fix1 +``` + +The command will push the new branch fix1 into your remote repository REMOTE_NAME that you created earlier. Additionally, it will also display a link that you can click on to open the new pull request. After clicking on the link, write a title and a concise description then click the β€œCreate” button. + +Yay you are now all set. Ω©(ΛŠα—œΛ‹*)و + +## Contributing Code + +### Adding a primitive + +A primitive is a built-in function or operator which is a core part of the language. It is represented by a glyph, which it may share with another primitive. More information [here](https://aplwiki.com/wiki/Primitive) + +Ullu tests the primitives one-by-one covering all the code written in the sources of Dyalog APL, all possible cases including edge cases and all types of inputs it can receive. + + + + +A workflow demonstration blog on how to write tests is upcomming. Progress can be tracked [here](https://github.com/Dyalog/ullu/issues/50) + + + + + +## Contributing Docs + +### Decision docs + + +Decision Docs are records detailing key decisions, fostering transparency and aiding future collaboration by providing a structured account of the decision-making process. Documentation about why certain decisions were taken in the codebase, it basically explains the mindset of the developer writing the tests and it also documents all the anomalies in the codebase. + +It can be found [here](https://github.com/Dyalog/ullu/tree/docs-revamp/docs/decision) + + +In the decision docs, you need to mention the types of test cases included in the tests, description of all the variations of the tests and all the edge cases that were faced/handled. It needs to have all the information that a person in the future would need to expand the same tests or write new related ones. All the decisions taken while writing the tests. + + +Decision docs for the primitive Magnitude are a good example of this. It can be found [here](https://github.com/Dyalog/ullu/blob/docs-revamp/docs/decision/primitive-functions/scalar-monadic.md#magnitude-rydocs) + +--- + +Note: By submitting a PR you agree to license your contribution under the ullu’s MIT [license](https://github.com/Dyalog/ullu/blob/main/LICENSE) unless explicitly noted otherwise. \ No newline at end of file diff --git a/docs/decision/readme.md b/docs/decision/readme.md new file mode 100644 index 0000000..3f3561f --- /dev/null +++ b/docs/decision/readme.md @@ -0,0 +1,3 @@ +# Decision Docs + +Decision Docs are records detailing key decisions, fostering transparency and aiding future collaboration by providing a structured account of the decision-making process. Documentation about why certain decisions were taken in the codebase, it basically explains the mindset of the developer writing the tests and it also documents all the anomalies in the codebase. \ No newline at end of file diff --git a/readme.md b/readme.md index d859bd2..40723f6 100644 --- a/readme.md +++ b/readme.md @@ -8,20 +8,20 @@ ## πŸ€” What is ullu? -Ullu is a QA for DyalogAPL (can be used to test any APL) which tests specifically the functionality of primitives. +Ullu is a QA for DyalogAPL (can be used to test any APL ideally) which tests specifically the functionality of primitives one-by-one. The main focus of this test suite is to find bugs, irregularities, edge cases and code coverage. ## 🎿 Coverage ### πŸ’ͺ Available Tests - floor (monadic ⌊) -- index of (dyadic ⍳) - magnitude (monadic |) -- membership (dyadic ∊) - residue (dyadic |) +- unique (monadic βˆͺ) ### 🧱 Under progress -- unique (monadic βˆͺ) -- unique mask (monadic β‰ ) +- index of (dyadic ⍳) (Not tested for coverage) +- membership (dyadic ∊) (Not tested for coverage) +- unique mask (monadic β‰ ) (Next Up with #44) ## ✍ The name @@ -31,6 +31,8 @@ Just as the owl represents both wisdom and foolishness the QA also has a dual na ## ⬇ Usage +You can use ullu in a dyalog session on any supported operating system. + ### Quick Run Run tests using dyalogscript: @@ -73,6 +75,18 @@ or unittest.RunTests tests.membership ``` +### πŸ”— More documentation + +- [Contributing.md](https://github.com/Dyalog/ullu/blob/main/contributing.md): Guide on how to contribute to the codebase +- [Decision docs](https://github.com/Dyalog/ullu/tree/main/docs/decision): Explains the decisions taken with each step of the codebase and also documents anomalies for future users. + + +### πŸ”— Suggestions/Questions + +Feel free to open GitHub issues for any questions, suggestions or features requests + +If you want to reach out, please email `aarush[at]dyalog.com` + ## βš– Licence