Skip to content

Minor revisions to contributor's guide #113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 16, 2021
Merged

Minor revisions to contributor's guide #113

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9e55f99
Minor revisions to contributor's guide
clyne Jun 15, 2021
89ae543
Reviewer comments - use ```{Note}``` for callouts
clyne Jun 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 1 addition & 45 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,48 +5,4 @@
This is the source repository for the [Project Pythia portal](https://projectpythia.github.io).
The portal site is built with [sphinx](https://www.sphinx-doc.org/).

To build the site locally (e.g. for testing new content),
use [conda](https://docs.conda.io/) to set up a build environment with all dependencies.

First, make a local clone of this source repository on your machine. For example:

```
git clone https://github.com/ProjectPythia/projectpythia.github.io.git
```

Then, change working directories to the local repository's `content` directory:

```
cd projectpythia.github.io/content
```

Set up your a conda environment:

```
conda env create -f ../ci/environment.yml
conda activate pythia
```

You can then build the site with:

```
make html
```

After building the site it may be possible to preview the portal in your web browser by simply opening the `index.html` file:

```
open _build/html/index.html
```

However, many of the links will not work. For all of the links found in the portal to work properly, you'll need to set up a local testing server. This can be done with Python's http.server by running the following command from within the `content` directory:

```
python -m http.server --directory _build/html/
```

and then pointing your browser at the URL: `localhost:8000`.

More information on setting up a local test server is available from [here](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/set_up_a_local_testing_server)

You can find more details in the [Contributor's Guide](https://projectpythia.org/pages/contributing.html).
Information on contributing is available [here](CONTRIBUTING.md)
65 changes: 40 additions & 25 deletions content/pages/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,11 +124,13 @@ command line tool for collaborative software version control, while
GitHub is an online, web-accessible service that greatly simplifies
using the powerful, yet often complex, Git.

> **Note:** GitHub operates entirely within a web browser. You do not
> need to install anything, but you will need to set up a free GitHub
> account. Git is a command line tool that is most likely already
> installed on your machine, and will need to be run from a “terminal” window, AKA
> a “shell”.
```{Note}
GitHub operates entirely within a web browser. You do not
need to install anything, but you will need to set up a free GitHub
account. Git is a command line tool that is most likely already
installed on your machine, and will need to be run from a “terminal” window, AKA
a “shell”.
```

Using, and even just configuring, Git and GitHub are often the most
daunting aspects of contributing to a GitHub hosted project. Here
Expand Down Expand Up @@ -195,9 +197,6 @@ The steps:
conda update conda
```

Make sure that you have cloned the repository as described above
in Forking a Repository.

At this point you have a current version of conda available on your
desktop or laptop. Before using your conda environment to work on
Pythia content, you'll need to perform an addtional one-time setup
Expand All @@ -207,6 +206,14 @@ you wish to use it. Consult the repo-specific contributor’s guide
for information on “Building the site”, and
follow the steps described therein.

```{Note}
Repository-specific contributor's
information can always be accessed by navigating your web browser
to the appropriate Project Pythia GitHub repository,
[here](https://github.com/ProjectPythia/pythia-foundations) for
example, and clicking on the file named `CONTRIBUTING.md`
```

More information on installing and using conda may be found
[here](https://foundations.projectpythia.org/foundations/conda.html).

Expand All @@ -230,14 +237,14 @@ summarized below, and described in detail
The steps:

1. Navigate your web browser to the Pythia repository that you wish
to contribute to.
1. Click on the “Fork” icon. This will create a copy of the Pythia repository
to contribute to. For example, [here](https://github.com/ProjectPythia/pythia-foundations).
1. Click on the “Fork” icon (upper right). This will create a copy of the Pythia repository
on the GitHub server under **your** account name. You may be prompted
to sign in. If so, use the GitHub (not Git) account name and password
that you created when you created your GitHub account above.
1. After successfully forking a Pythia repo you should have a copy
of that repository on the GitHub server under your account name.
To verify this you can navigate to GitHub, sign in if you are not
To verify this you can navigate to the GitHub [home page](https://github.com/), sign in if you are not
already, and click on “your repositories” under the pull down menu
in the top right corner of the page. You should see the Pythia
repository you just cloned listed. Click on it. This is a remote
Expand Down Expand Up @@ -300,24 +307,26 @@ on this later.

For further information see the [GitHub docs on forking a repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo).

Remember: at this point you should have a local copy of the repository
```{Note}
At this point you should have a local copy of the repository
in your current working directory. You can safely make changes to
any of the contents. Once you are ready to contribute your changes
back to the Pythia repository you will need to submit a Pull Request
(PR), described later.
```

### Make your local changes

At this point you should be able to make your desired changes to
the local copies of your files. Consult the repo-specific contributor’s
guide for information specific to the repo you are working on.
the local copies of your files. **Always consult the repo-specific contributor’s
guide for information specific to the repo you are working on.**

### Submit a Pull Request (PR)

Once you have completed making changes to your local copy of a
Pythia repository and are ready to have your changes merged with a
Pythia repository on GitHub, you need to essentially perform the
reverse processed used to acquire a copy of the Pythia repo, and
reverse process used to acquire a copy of the Pythia repo, and
submit a PR asking the Pythia maintainers to consider your merge
request. The merge will occur between your personal GitHub repository
and the Pythia GitHub repository, so you first need to merge any
Expand Down Expand Up @@ -362,10 +371,12 @@ $ git commit PATH_TO_NEW_FILE

Which will prompt you for a log message. Please provide something informative. If you make lots of changes, it is best to make multiple commits, broken up into related chunks. E.g. “fixed x”, “added documentation”, “added testing”.

> **Note:** When executing `git commit` after `git add PATH_TO_NEW_FILE`,
> specifying the path to the new file isn't stricly necessary. However,
> in other instances the file path argument is required. We include it
> here to keep things simple.
```{Note}
When executing `git commit` after `git add PATH_TO_NEW_FILE`,
specifying the path to the new file isn't stricly necessary. However,
in other instances the file path argument is required. We include it
here to keep things simple.
```

Depending on which repo you are making changes to, a `pre-commit`
[hook](https://www.atlassian.com/git/tutorials/git-hooks)
Expand All @@ -381,11 +392,13 @@ $ git status

after your `commit` to verify everything looks as expected.

> **Note:** `pre-commit` _hooks_ can sometimes be difficult to satisfy. You
> can always tell **git** not to run the _hook_ by
> running `git commit --no-verify`.
> This will allow you to submit your changes (see steps) below, and get help
> later from a Project Pythia maintainer.
```{Note}
`pre-commit` _hooks_ can sometimes be difficult to satisfy. You
can always tell **git** not to run the _hook_ by
running `git commit --no-verify`.
This will allow you to submit your changes (see steps) below, and get help
later from a Project Pythia maintainer.
```

#### Pushing Your Changes to Your Personal GitHub Repository

Expand All @@ -406,7 +419,9 @@ the name should be _issue_XXX_ where _XXX_ is the issue number.
After successfully running this command your changes will now be
on GitHub under your personal account, but they are not yet part
of the Pythia repo. For that to happen one more step is required:
submitting a pull request.
you must **Make the PR**.

But first:

#### Review your Code

Expand Down