Merge pull request #65 from defactor-com/feat/add-contributing-guidel…

…ines

Feat/add contributing guidelines

docs/introduction/_category_.json

@@ -0,0 +1,9 @@
+{
+    "label": "Introduction",
+    "position": 1,
+    "link": {
+      "type": "doc",
+      "id": "introduction/index"
+    }
+  }
+

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.

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.
+
+<img src="/img/github-flow.webp" width="958" height="241" className="centerImg" alt="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:
+
+```
+<type>/<task-description>-<issue-number>
+```
+
+* 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**:
+
+```
+<type>(<scope>): <subject>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+The ```header``` is mandatory and the ```scope``` of the header is optional.
+
+**Example:**
+
+```
+feat(scope): subject
+^--^ ^---^   ^-----^
+|    |       |
+|    |       +-> description in present tense. 
+|    |     
+|    +-> scope is usually the service worked on (webapp, hapi, hasura etc.)
+|
++-> Type: build, ci, docs, feat, fix, perf, refactor, style, test, content, or devtools.
+```
+
+The commit message cannot be longer than 100 characters. This allows the message to be easy to read on GitHub as well as various `git tools`.
+
+The footer should contain a [closing reference to an issue](https://help.github.com/articles/closing-issues-via-commit-messages/) if any.
+
+**The commit message should look like the following examples:**
+```
+feat(webapp): add a new react component for logo
+```
+
+```
+docs(changelog): update changelog to beta.5
+```
+
+```
+ci(github): update build and deploy workflow
+
+The version in our package.json gets copied to the one we publish, and users need the latest of these.
+```
+
+Even more [examples](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)
+
+### Revert
+
+If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit. In the body it should say: `This reverts commit <hash>`, where the hash is the SHA of the commit being reverted.
+
+### Type
+
+* **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm).
+* **chore**: What a user would not see (changes to the build process, configuration, etc).
+* **ci**: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs).
+* **docs**: Documentation only changes.
+* **feat**: A new feature for the user.
+* **fix**: A bug fix for the user.
+* **perf**: A code change that improves performance.
+* **refactor**: A code change that neither fixes a bug nor adds a feature (renaming a variable).
+* **revert**: Reverts a previous commit.
+* **style**: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc).
+* **test**: Adding missing tests or correcting existing tests.
+* **content**: Adding or removing content.
+* **devtools**: Developer tooling related.
+
+### Scope
+
+The scope is the name of the component or service that it affects. Eg:
+
+* **common**
+* **smart-contracts**
+* **webapp**
+* **storage**
+* **graphql**
+* **frontend**
+* **demux**
+* **docker**
+
+### Subject
+The subject contains a succinct description of the change:
+
+* use the imperative, present tense: "change" not "changed" nor "changes"
+* don't capitalize the first letter
+* no dot (.) at the end
+
+### Body
+Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes".
+The body should include the motivation for the change and contrast this with previous behavior.
+
+### Footer
+
+The footer should contain any information about **Breaking Changes** and is also the place to
+reference GitHub `issues` that this commit closes.
+
+**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines. The rest of the commit message is then used for this.
+
+## Reporting Bugs
+
+Before submitting your `issue` please check that you've completed the following steps:
+
+* Made sure you're on the latest version.
+* Used the search feature to ensure that the bug hasn't been reported before.
+
+Bug reports should contain the following information:
+
+* Summary: A brief description.
+* Steps to reproduce: How did you encounter the bug? Instructions to reproduce it.
+* Expected behavior: How did you expect it to behave?
+* Actual behavior: How did it actually behave?
+* References: Links to any related tickets or information sources.
+* If possible, attach visual documentation of the bug. Screenshot or animated gif.
+
+## Releases
+
+We release the production software version using github tags following [Semver](http://semver.org), except the version roles have the semantic names, "Breaking.Feature.Fix" instead of "Major.Minor.Patch".
+
+#### Breaking.Feature.Fix
+
+We don't decide what the version will be. The API changes decide. Version numbers are for computers, not people. Release names are for people.
+
+##### Breaking
+
+Any breaking change, no matter how small increments the Breaking version number. Incrementing the Breaking version number has absolutely no relationship with issuing a release.
+
+##### Feature
+
+When any new feature is added. This could be as small as a new public property, or as large as a new module contract being exposed.
+
+##### Fix
+
+When a documented feature does not behave as documented, or when a security issue is discovered and fixed without altering documented behavior.
+
+### Changelog Generation
+
+On each release we generate a changelog file to document changes using the standard [git-changelog](https://github.com/rafinskipg/git-changelog) package. There's an npm task for it.
+
+## Advanced Git Tools
+
+There are also tools like [Hub](https://hub.github.com/) and [git-extras](https://github.com/tj/git-extras) that facilitate interacting with Github. You can leverage these tools to contribute to this repository.
+
+## Code Standards
+
+We use the [standardjs code style](https://standardjs.com).
+
+## Continuous Integration and Delivery
+
+We will use github actions for CI/CD deployments.
+
+## Pre-commit Hooks
+
+We use pre-commit hooks to ensure that both the code standards and commit message conventions are met.

docusaurus.config.js

@@ -11,13 +11,11 @@ const config = {
   title: 'Defactor Developer Docs',
   tagline: 'Technical Documentation for Defactor Developers',
   favicon: 'img/Defactor_Favicon-32x32.png',
-
   // Set the production url of your site here
   url: 'https://defactor.dev',
   // Set the /<baseUrl>/ pathname under which your site is served
   // For GitHub pages deployment, it is often '/<projectName>/'
   baseUrl: '/',
-
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.
   organizationName: 'defactor-com', // Usually your GitHub org/user name.

static/CNAME

@@ -0,0 +1 @@
+defactor.dev