Skip to content

Commit

Permalink
docs: Contribute update, remove flask refs
Browse files Browse the repository at this point in the history
  • Loading branch information
@PWA-GouldA
PWA-GouldA committed Mar 14, 2024
1 parent 9a0b4fd commit 1107f8d
Show file tree
Hide file tree
Showing 3 changed files with 136 additions and 95 deletions.
58 changes: 51 additions & 7 deletions .obsidian/workspace.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,16 @@
"type": "split",
"children": [
{
"id": "35974611d054e0dc",
"id": "24d108f19bd80217",
"type": "tabs",
"children": [
{
"id": "ffb884bc76ff47e7",
"id": "08eecd3350f5b33e",
"type": "leaf",
"state": {
"type": "markdown",
"state": {
"file": "CONTRIBUTE.md",
"file": "docs/14-forking-over-code.md",
"mode": "source",
"source": false
}
Expand Down Expand Up @@ -85,7 +85,7 @@
"state": {
"type": "backlink",
"state": {
"file": "CONTRIBUTE.md",
"file": "docs/14-forking-over-code.md",
"collapseAll": false,
"extraContext": false,
"sortOrder": "alphabetical",
Expand All @@ -102,7 +102,7 @@
"state": {
"type": "outgoing-link",
"state": {
"file": "CONTRIBUTE.md",
"file": "docs/14-forking-over-code.md",
"linksCollapsed": false,
"unlinkedCollapsed": true
}
Expand All @@ -125,7 +125,7 @@
"state": {
"type": "outline",
"state": {
"file": "CONTRIBUTE.md"
"file": "docs/14-forking-over-code.md"
}
}
}
Expand All @@ -147,7 +147,51 @@
"table-editor-obsidian:Advanced Tables Toolbar": false
}
},
"active": "ffb884bc76ff47e7",
"active": "08eecd3350f5b33e",
"lastOpenFiles": [
"CONTRIBUTE.md",
"docs/98-command-line-extras.md",
"docs/14-forking-over-code.md",
"docs/15-workflows.md",
"assets/pasted-image-20240314105028.png",
"assets/pasted-image-20240314102512.png",
"assets/front-cover.svg",
"assets/back-cover.svg",
"assets/BLANK_README.md",
"LICENSE.md",
"CHANGELOG.md",
"output",
"docs/00-Back.md.md",
"docs/00-Front.md.md",
"assets/pasted-image-20240216114456.png",
"assets/pasted-image-20240216124422.png",
"docs/99-references-and-resources.md",
"docs/08-status-add-commit.md",
"docs/06-read-me.md",
"ReadMe.md",
"theme/style.css",
"theme",
"docs/13-why-hello-dolly.md",
"docs/12-remotely-useful.md",
"docs/11-merging-and-conflicts.md",
"docs/10-shaking-the-tree.md",
"docs/09-git-history.md",
"docs/07-ignore-me.md",
"docs/05-global-settings.md",
"docs/04-git-started.md",
"docs/02-getting-ready.md",
"docs/03-repositories-and-folders.md",
"docs/01-what-is-version-control.md",
"docs",
"assets/brave_dWSQwZYc3F.mp4",
"assets/2024-03-01_15_03_52-AdyGCode_git-remote-demo-ii-Brave.png",
"assets/2024-03-01_14_57_49-New-repository-Brave.png",
"assets/2024-03-01_14_57_43-New-repository-Brave.png",
"assets/2024-03-01_14_57_37-New-repository-Brave.png",
"99-references-and-resources.md",
"themes",
"ReadMe.md~",
"02-getting-ready.md~",
"assets"
]
}
126 changes: 38 additions & 88 deletions CONTRIBUTE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,21 @@ Thank you for considering contributing to this tutorial repository!

[](CONTRIBUTE.md#support-questions)

Please don't use the issue tracker for this. The issue tracker is a tool to address bugs and feature requests in Flask itself. Use one of the following resources for questions about using Flask or issues with your own code:
Please don't use the issue tracker for this. The issue tracker is a tool to address bugs and feature requests for the project itself.

- The `#questions` channel on our Discord chat: [https://discord.gg/pallets](https://discord.gg/pallets)
- Ask on [Stack Overflow](https://stackoverflow.com/questions/tagged/flask?tab=Frequent). Search with Google first using: `site:stackoverflow.com flask {search term, exception message, etc.}`
- Ask on our [GitHub Discussions](https://github.com/pallets/flask/discussions) for long term discussion or larger questions.
Use one of the following resources for questions about the project:

- Ask on our [GitHub Discussions](https://github.com/AdyGCode/Intro-to-Version-Control/discussions/) for long term discussion or larger questions.

## Reporting issues

[](https://github.com/pallets/flask/blob/main/CONTRIBUTING.rst#reporting-issues)

Include the following information in your post:

- Describe what you expected to happen.
- If possible, include a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) to help us identify the issue. This also helps check that the issue is not with your own code.
- Describe what actually happened. Include the full traceback if there was an exception.
- List your Python and Flask versions. If possible, check if this issue is already fixed in the latest releases or the latest code in the repository.
- Before reporting a problem, check if this issue is already fixed in the latest releases or the latest code in the repository.
- Provide a title that gives a basic indicator of the yuou have. For example "Content missing: Chapter 7 No content", or "Grammar: Chapter 4"
- Provide a possible solution, if you are able to do so.

## Submitting patches

Expand All @@ -31,72 +30,51 @@ If there is not an open issue for what you want to submit, prefer opening one fo

Include the following in your patch:

- Use [Black](https://black.readthedocs.io/) to format your code. This and other tools will run automatically if you install [pre-commit](https://pre-commit.com/) using the instructions below.
- Include tests if your patch adds or changes code. Make sure the test fails without your patch.
- Update any relevant docs pages and docstrings. Docs pages and docstrings should be wrapped at 72 characters.
- Add an entry in `CHANGES.rst`. Use the same style as other entries. Also include `.. versionchanged::` inline changelogs in relevant docstrings.

### First time setup using GitHub Codespaces

[](https://github.com/pallets/flask/blob/main/CONTRIBUTING.rst#first-time-setup-using-github-codespaces)

[GitHub Codespaces](https://docs.github.com/en/codespaces) creates a development environment that is already set up for the project. By default it opens in Visual Studio Code for the Web, but this can be changed in your GitHub profile settings to use Visual Studio Code or JetBrains PyCharm on your local computer.

- Make sure you have a [GitHub account](https://github.com/join).
- From the project's repository page, click the green "Code" button and then "Create codespace on main".
- The codespace will be set up, then Visual Studio Code will open. However, you'll need to wait a bit longer for the Python extension to be installed. You'll know it's ready when the terminal at the bottom shows that the virtualenv was activated.
- Check out a branch and [start coding](https://github.com/pallets/flask/blob/main/CONTRIBUTING.rst#start-coding).
- Update any relevant documents and images.
- Add an entry in `CHANGELOG.md`. Use the same style as other entries.

### First time setup in your local environment

[](https://github.com/pallets/flask/blob/main/CONTRIBUTING.rst#first-time-setup-in-your-local-environment)

- Make sure you have a [GitHub account](https://github.com/join).

- Download and install the [latest version of git](https://git-scm.com/downloads).

- Configure git with your [username](https://docs.github.com/en/github/using-git/setting-your-username-in-git) and [email](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address).

$ git config --global user.name 'your name'
$ git config --global user.email 'your email'

- Fork Flask to your GitHub account by clicking the [Fork](https://github.com/pallets/flask/fork) button.

```bash
git config --global user.name 'your name'
git config --global user.email 'your email'
```

- Fork this repository to your GitHub account by clicking the [Fork](https://github.com/AdyGCode/Intro-to-Version-Control/fork) button.

- [Clone](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#step-2-create-a-local-clone-of-your-fork) your fork locally, replacing `your-username` in the command below with your actual username.

$ git clone https://github.com/your-username/flask
$ cd flask

- Create a virtualenv. Use the latest version of Python.

- Linux/macOS

$ python3 -m venv .venv
$ . .venv/bin/activate

- Windows

> py -3 -m venv .venv
> .venv\Scripts\activate
- Install the development dependencies, then install Flask in editable mode.

$ python -m pip install -U pip
$ pip install -r requirements/dev.txt && pip install -e .

- Install the pre-commit hooks.

$ pre-commit install --install-hooks

```bash
git clone https://github.com/your-username/Intro-to-Version-Control.git
cd Intro-to-Version-Control
```


### Start coding
### Start Editing and Documenting

[](https://github.com/pallets/flask/blob/main/CONTRIBUTING.rst#start-coding)

- Create a branch to identify the issue you would like to work on. If you're submitting a bug or documentation fix, branch off of the latest ".x" branch.
- Create a branch to identify the issue you would like to work on using the following rules:

- If you are adding a new chapter, branch off the `dev` branch. Name your branch `feat/feature_name`.


```bash
git fetch origin
git checkout -b feat/feature_name origin/2.0.x
```

- If you're submitting a bug or documentation fix, branch off of the latest main branch. Name your fix `fix/`




$ git fetch origin
$ git checkout -b your-branch-name origin/2.0.x

If you're submitting a feature addition or change, branch off of the "main" branch.

Expand All @@ -113,34 +91,6 @@ Include the following in your patch:
$ git push --set-upstream origin your-branch-name


### Running the tests

[](https://github.com/pallets/flask/blob/main/CONTRIBUTING.rst#running-the-tests)

Run the basic test suite with pytest.

$ pytest

This runs the tests for the current environment, which is usually sufficient. CI will run the full suite when you submit your pull request. You can run the full test suite with tox if you don't want to wait.

$ tox

### Running test coverage

[](https://github.com/pallets/flask/blob/main/CONTRIBUTING.rst#running-test-coverage)

Generating a report of lines that do not have test coverage can indicate where to start contributing. Run `pytest` using `coverage` and generate a report.

If you are using GitHub Codespaces, `coverage` is already installed so you can skip the installation command.

$ pip install coverage
$ coverage run -m pytest
$ coverage html

Open `htmlcov/index.html` in your browser to explore the report.

Read more about [coverage](https://coverage.readthedocs.io/).

### Building the docs

[](https://github.com/pallets/flask/blob/main/CONTRIBUTING.rst#building-the-docs)
Expand Down
47 changes: 47 additions & 0 deletions docs/14-forking-over-code.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,52 @@ The concept of a fork is a GitHub feature. It basically clones the repository to

In return, GitHub maintains a link back to the original to allow collaboration on the project/repository.

## Why Fork

There are two main reasons:
1. Go your own way
2. Contribute

### Go your own way

This type of fork allows you freedom to take the project in a totally new direction.

It allows you to experiment, learn and grow.

It provides you with the opportunity to develop a new application or system based on the original, and then the ability to not look back!

Another part of this is that you still get the original project's updated code, bug fixes etc to be merged into your code at your discretion.

This type of fork gives you complete control of your project.

### Contribute

In the contribution type of fork, you are using the fork almost like a branch.

The big thing about this is that you only need read permissions to the original repo to start working.

## Forking in the Enterprise

Remember that forking is a GitHub feature. Other Git hosting solutions may have similar features.

Forking is common practice in open source development.


## Comparing Forks v Branches


| | Forks | Branches |
| ----------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **Purpose** | Create a separate copy of a repository for significant changes or different directions | Develop new features or fix bugs without disrupting the main codebase |
| **Relationship to the original codebase** | Completely independent repository | Linked to the original repository |
| **Ownership** | Owned by the user who created them | Owned by the repository owner |
| **Scope of changes** | Typically involve significant changes | Typically involve smaller changes |
| **Collaboration** | Used to develop ideas in isolation from the main team | Used to develop ideas that the main team is working on |

Based on SSW.Rules "Do you know when to create a fork vs a branch".

SSW.Rules. (n.d.). _Git - Do you know when to create a fork vs a branch?_ [online] Available at: https://www.ssw.com.au/rules/fork-vs-branch/ [Accessed 14 Mar. 2024].

## How to Fork

Forking is done within the GitHub Web GUI.
Expand All @@ -30,3 +76,4 @@ The basic process is:
- Read the ReadMe and any documentation on how to fork and contribute to the repository
- Fork the repository (to your account)
- Clone the repository to your local device

0 comments on commit 1107f8d

Please sign in to comment.