diff --git a/README.md b/README.md index 71059c553..84b325387 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/content/pages/contributing.md b/content/pages/contributing.md index 5c39dc191..8ce75c4c0 100644 --- a/content/pages/contributing.md +++ b/content/pages/contributing.md @@ -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 @@ -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 @@ -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). @@ -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 @@ -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 @@ -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) @@ -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 @@ -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