From 1376456d435091530d8072ddf8d068c6f898c09b Mon Sep 17 00:00:00 2001 From: Xavier Fernandez Date: Mon, 22 Jan 2024 17:50:46 -0600 Subject: [PATCH 1/3] docs(agile): Added Contributing Guidelines and Agile Process --- docs/introduction/_category_.json | 9 + docs/introduction/agile-playbook.md | 90 +++++++ .../index copy.md} | 0 docs/introduction/index.md | 58 +++++ docs/introduction/open-source-guidelines.md | 231 ++++++++++++++++++ static/img/github-flow.webp | Bin 0 -> 10476 bytes 6 files changed, 388 insertions(+) create mode 100644 docs/introduction/_category_.json create mode 100644 docs/introduction/agile-playbook.md rename docs/{introduction.md => introduction/index copy.md} (100%) create mode 100644 docs/introduction/index.md create mode 100644 docs/introduction/open-source-guidelines.md create mode 100644 static/img/github-flow.webp diff --git a/docs/introduction/_category_.json b/docs/introduction/_category_.json new file mode 100644 index 00000000..8ef97a50 --- /dev/null +++ b/docs/introduction/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Introduction", + "position": 1, + "link": { + "type": "doc", + "id": "introduction/index" + } + } + \ No newline at end of file diff --git a/docs/introduction/agile-playbook.md b/docs/introduction/agile-playbook.md new file mode 100644 index 00000000..4e907d3c --- /dev/null +++ b/docs/introduction/agile-playbook.md @@ -0,0 +1,90 @@ +--- +title: Agile Development Workflow +sidebar_position: 3 +--- + +# Agile Development Workflow at Defactor + +Defactor's Agile Development Workflow documentation provides an in-depth guide to our iterative and incremental approach to software development. This workflow emphasizes collaboration, customer feedback, and rapid releases to enhance project transparency and efficiency. + +## Agile Principles at Defactor + +Agile at Defactor is about: + +- **Quick Wins**: Delivering small product increments for feedback and iteration. +- **Quality**: Rigorously testing each increment. +- **Time Management**: Using time-boxed sprints, usually two weeks long. +- **Scope Management**: Prioritizing work to deliver the most valuable features first. + +Refer to the [Agile Manifesto](https://agilemanifesto.org/) for foundational principles. + +## Key Agile Roles + +- **Product Owner**: Manages the product backlog and ensures product success. +- **Scrum Master**: Oversees the Agile process and removes impediments. +- **The Team**: Delivers high-quality work in collaboration. + +The [Scrum Guide](https://scrumguides.org/) offers further insights into these roles. + +## Agile Artifacts + +- **Epic**: A large body of work that encompasses significant functionality. +- **Feature**: An enhancement that delivers value and aligns with an Epic. +- **User Story**: A requirement from the user's perspective. +- **Task**: The smallest work unit to achieve a user story. + +## Release Planning Process + +1. **Identify Features**: Define what is needed for upcoming releases. +2. **Analyze Features**: Research and create a feature list. +3. **Prioritize**: Order the backlog by business value. +4. **Define Features**: Clearly outline features with acceptance criteria. +5. **Plan Releases**: Schedule feature development. +6. **Map Execution**: Visualize the feature delivery timeline. + +## Agile Framework and Ceremonies + +- **Backlog Grooming**: Refine user stories and defects. +- **Sprint Planning**: Choose user stories for the sprint. +- **Daily Stand-Ups**: Update on progress and impediments. +- **Sprint Review**: Showcase completed work. +- **Retrospective**: Reflect to improve the next sprint. + +## Sprint Ceremonies Detailed + +### Sprint Review +- **Goal**: Validate sprint outcomes with Product Owner approval. +- **Participants**: Scrum Master, Product Owner, Scrum Team, Stakeholders. +- **When**: End of the sprint. + +### Test Review +- **Goal**: Analyze defects and testing outcomes from the sprint. +- **Participants**: Scrum Master, Product Owner, Testers. +- **When**: After sprint completion. + +### Retrospective +- **Goal**: Enhance team collaboration and sprint effectiveness. +- **Participants**: Scrum Master, Scrum Team, Product Owner. +- **When**: Last day of the sprint. + +## Product Backlog Management + +The Product Backlog is dynamically managed, reflecting priorities and incorporating lessons learned. It is used to sequence sprint work and track progress across releases. + +## User Story Development + +User stories are crafted to provide value, are independently testable, and are sized to be completed within a sprint. They follow the INVEST criteria and are continuously refined. + +### Template for User Stories +- **Format**: As a `[role]`, I want `[action]` so that `[benefit]`. + +## User Story Best Practices + +1. **Complete Stories**: Deliver value in each sprint. +2. **Organized Work**: Enable demonstrable and testable stories. +3. **Story Decomposition**: Break down complex stories for sprint manageability. +4. **Independence**: Develop stand-alone stories to avoid upstream dependencies. + +## Conclusion + +This document is a primer on Agile practices at Defactor. For detailed procedures and methodologies, refer to the comprehensive Defactor Agile Playbook available to all team members. diff --git a/docs/introduction.md b/docs/introduction/index copy.md similarity index 100% rename from docs/introduction.md rename to docs/introduction/index copy.md diff --git a/docs/introduction/index.md b/docs/introduction/index.md new file mode 100644 index 00000000..32505524 --- /dev/null +++ b/docs/introduction/index.md @@ -0,0 +1,58 @@ +--- +title: Introduction to Defactor +sidebar_position: 1 +--- + +Defactor is an innovative platform at the convergence of real-world assets (RWA) and decentralized finance (DeFi). It provides a comprehensive decentralized open-source toolkit for asset tokenization, enabling businesses to access DeFi liquidity backed by real-world value. + +## Core Pillars of Defactor + +- **Technology & Innovation:** Pioneering innovation in RWA and DeFi, reducing time to market for businesses and providing DeFi liquidity. +- **Governance:** Encouraging community collaboration and driving innovation in RWA tokenization. +- **Community:** Building a global support system valuing contributions and participation. +- **Liquidity & Markets:** Ensuring token availability and market liquidity, nurturing partnerships, and monitoring market conditions. + +## Defactor's Role in Blockchain Ecosystem + +Defactor plays a crucial role in bridging the gap between traditional finance and DeFi. By tokenizing real-world assets, it opens new avenues for investment, funding, and economic growth, while providing the security and efficiency of blockchain technology. + +# Tokenized Real World Assets + +Tokenized real-world assets refer to the representation of tangible or intangible assets as digital tokens on a blockchain. These tokens reflect the value and ownership of their real-world counterparts, offering a bridge between traditional finance (TradFi) and decentralized finance (DeFi). + +## Advantages of Tokenization + +- **Liquidity:** Tokenization can increase the liquidity of traditionally illiquid assets like real estate or art. +- **Accessibility:** Broadens the accessibility to investment opportunities, allowing fractional ownership. +- **Efficiency:** Streamlines processes, reducing the need for intermediaries and lowering transaction costs. +- **Transparency and Security:** Blockchain technology ensures transparent, secure, and tamper-proof record-keeping. + +## Purpose of the Developer Documentation + +This developer documentation is designed to be a comprehensive guide for understanding and interacting with the Defactor platform and its associated technologies. It serves several key purposes: + +- **Educational Resource:** To educate developers about the Defactor ecosystem, including its integration with blockchain technologies, tokenization of real-world assets, and Web3. +- **Technical Reference:** To provide in-depth technical information, API references, and code examples for developers building on or integrating with the Defactor platform. +- **Best Practices Guide:** To offer guidance on best practices in developing, deploying, and maintaining applications within the Defactor ecosystem. +- **Community Engagement:** To foster a community of developers by providing a common resource that encourages collaboration and innovation. + +## Target Audience + +The target audience for this documentation includes: + +- **Blockchain Developers:** Individuals with experience in blockchain technology, smart contracts, and decentralized applications (DApps), looking to expand their expertise into the Defactor ecosystem. +- **Fintech Developers:** Professionals in the fintech sector who are interested in exploring and leveraging the capabilities of blockchain and decentralized finance (DeFi) for real-world asset tokenization. +- **Software Engineers:** General software developers seeking to understand the technical aspects of the Defactor platform and how it integrates with the broader blockchain and Web3 landscape. +- **Technical Decision Makers:** CTOs, technical leads, and other decision-makers evaluating the Defactor platform for potential use in their projects or businesses. + +## How to Navigate the Documentation + +Navigating this documentation is straightforward, with the content organized into several key sections: + +- **Getting Started:** Introduction to the basic concepts, setup instructions, and quick start guides for new users. +- **Technical Overview:** Detailed explanations of the Defactor platform, including its architecture, key components, and how it interacts with blockchain networks and Web3. +- **API Documentation:** Comprehensive reference material for the Defactor APIs, including endpoints, parameters, and sample requests and responses. +- **Development Guides:** Step-by-step tutorials and guides for common development tasks, use cases, and integration scenarios. +- **FAQ and Troubleshooting:** A section dedicated to frequently asked questions and troubleshooting common issues encountered by developers. + +Each section is designed to be self-contained, allowing you to quickly find the specific information you need. Additionally, a search function is available for locating topics or keywords within the documentation. diff --git a/docs/introduction/open-source-guidelines.md b/docs/introduction/open-source-guidelines.md new file mode 100644 index 00000000..deb3dffc --- /dev/null +++ b/docs/introduction/open-source-guidelines.md @@ -0,0 +1,231 @@ +--- +id: open-source-guidelines +title: Open Source Contributing Guidelines +sidebar_label: Open Source Guidelines +sidebar_position: 2 +description: Guidelines for contributing to open source projects +keywords: [Open Source, Contributing, Guidelines, Open Source Contributing Guidelines, open source, open source guidelines, Open Source Projects] +--- + +## Development Process + +We use a Kanban-style board to prioritize the work. For example this [Documentation Site's Project board](https://github.com/orgs/defactor-com/projects/11/views/1). + +We have added a additional column to the default automated board in order to maintain a prioritized `To Do` column. + +When a new issues is create you need to explicitly use the project option on the GitHub issue to include it in the board; Once you do that it gets automatically added to the New Issues column. + +Periodically we move the new Issues to the `To Do` column and manually and give it the appropriate priority. + +When you start working on a task you must manually move it to `In Progress` column. + +We use GitHub flow https://guides.github.com/introduction/flow/ to request code changes. +We develop on `master` and `release` using tags with semver versioning. + +Open Source Project Workflow on GitHub + +New and reopened `pull request` are automatically added to the board in the `In Progress` column. + +When the pull request is closed is moved to the `Done` column automatically. If the pull request closes and issues it is properly stated with the GitHub keywords closes in the pull request it gets automatically moved to the `Done` column too. + +## Branch Naming Convention + +Name every branch for your pull requests using the following simple convention: + +``` +/- +``` + +* Always use lowercase. +* Choose the [type](#type). +* Meaningful and short descriptions. +* Use hyphens as separators. +* Use the imperative, present tense: "change" not "changed" nor "changes". +* Use the ``issue`` number to reference it in the branch. + +-**Example**: + +``` +feat/new-feature-123 +^--^ ^---------^ ^-^ +| | | +| | +-> Issue number +| | +| +-> Short description of the task +| ++-> Type: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test, content, or devtools +``` + +## Pull Request General Guidelines + +* Please check to make sure that there aren't existing `pull request` attempting to address the `issue` mentioned. +* Check for related `issues` on the `issue tracker`. +* Non-trivial changes should be discussed on an issue first. +* Develop in a topic branch, never on master: `git checkout -b type/task-issue`. +* Provide useful `pull request` description. +* Make well scoped `atomic` pull requests. 1 PR per feature of bug fix. +* Link the `issue` on the `pull request` description for cross references between code and issues. + +We only support support **squash merge** of the `pull requests` as a best practice for ensure the `master` log is maintained clean and relevant, without requiring the pull request to be rebased. This strategy requires that all pull request made are `atomic`, in other words they solve one thing only. One pull request per feature, bug fix or documentation update. + +## Commit Message Guidelines + +We have very precise rules over how our `git` commit messages can be formatted, following GitHub conventions and standards. This leads to **more readable messages** that are easy to follow when looking through the **project history**. But also, we use the `git` commit messages to **generate the project change log**. + +We follow the commit message conventions as shown below: + +### Commit Message Format + +Each commit message consists of a **header**, a **body** and a **footer**. The header has a special +format that includes a **type**, a **scope** and a **subject**: + +``` +(): + + + +