Contributing to Fedora Websites

contwork.md

Adding your code to the repository

In order to contribute your code to the repository, a working Git installation, and an account on Pagure is required.

1. Install and configure Git, if not done already.
   1. Install Git
      1. On Fedora/CentOS/RHEL/OpenSUSE by executing the following command on a terminal.

         sudo dnf install git
         

      2. On Debian/Ubuntu/Linux Mint/KDE Neon/Pop!_OS by executing the following command on a terminal.

         sudo apt install git
         

      3. On Arch/Antergos/Manjaro/Endeavor by executing the following command on a terminal.

         sudo pacman -S git
         

   2. Configure Git
      1. Set the author identity by saving the name and email address with the following command. Execute without the --global flag if the identity is to be retained only for the current repository.

         git config --global user.email "<your-email-address>"
         

         git config --global user.name "<your-full-name>"
         

2. If an account is not available, create one by visiting https://accounts.fedoraproject.org. Once done, log into https://pagure.io to get started.

Go through the following steps in order to add your code to the repository.

1. Using an internet browser of your choice, navigate to https://pagure.io/fedora-websites.
2. Click on the Fork button in the top right corner of the page, and a copy of the repository would be created in your Pagure account.
3. Now head towards the recently created fork by navigating to https://pagure.io/fork/<your-username>/fedora-websites.
4. An SSH public key needs to be added in order to push commits to the fork in an authorized manner.
   1. If there is an SSH keypair available already, copy the SSH public key to your clipboard.
   2. If there is no SSH keypair available already, generate one by using the ssh-keygen -t rsa command and copy the contents of the SSH public key file to your clipboard.
5. Head towards the Deploy Keys section in Settings by navigating to https://pagure.io/fork/<your-username>/fedora-websites/settings#deploykey-tab.
6. Click on the Add Deploy Key button in the top right corner of the section to begin adding your SSH public key.
7. Paste your SSH public key in the box, enable the Push access checkmark and click on the Add button.
8. Now that the SSH public key is saved, head back towards the fork repository home by navigating to https://pagure.io/fork/<your-username>/fedora-websites.
9. Click on the Clone button in the top right corner of the screen and copy the SSH clone string from the popup, which looks like this ssh://[email protected]/forks/<your-username>/fedora-websites.git.
10. Open up a terminal in a directory where the repository would be cloned.
11. Execute the following command (with additional parameters if needed to accommodate custom-named SSH keypair files) to clone the fork repository.

    git clone ssh://[email protected]/forks/<your-username>/fedora-websites.git
    

12. Navigate into the cloned repository and feel free to pick an IDE and code editor of your choice to start working on the code.
13. Be sure to NOT work on the primary branch of the repository, which is master in this case. Keep the primary branch aside as a reference branch to create new branches out of and fallback to in case of scrapping.
14. Switch to a new branch and name it appropriately. For instance, a branch consisting of code for adding responsiveness to the header navigation bar may be named as fix-responsiveness-topnavbar.

    git checkout -b <branch-name-according-to-what-would-be-worked-on>
    

15. After on the working on the code, execute the following command to know about the changes made with additions, removals and modifications made in the tracked and untracked files.

    git status
    

16. Stage the changes of similar kind by executing the following command to prepare them to be committed. Please note that multiple changed files can be staged for single commit, but it is strongly recommended to keep dissimilar changes as separate commits.

    git add <file-that-was-changed>
    

17. Commit the staged changes to the checked out branch of your locally cloned fork by executing the following command while being sure that the commits made are signed. The commit message should be representative of the changes made in the said commit and preferably be under 50 chars.

    git commit -sm "<appropriate-commit-message>"
    

18. In order to reflect the locally made changes to your remote fork, the changes must be pushed.
    1. If there is no upstream branch available for the currently checked out local branch - which is generally the case when new branches are created locally, push can be made by executing the following command.

       git push --set-upstream origin <branch-name-according-to-what-would-be-worked-on>
       

    2. Once an upstream branch is available for the currently checked out local branch - which is generally the case after the above command has been executed, push can be made by executing the following command.

       git push origin <branch-name-according-to-what-would-be-worked-on>
       

19. Using an internet browser of your choice, open the Branches tab of the Source section of your fork by navigating to https://pagure.io/fork/t0xic0der/fedora-websites/branches to find your branch pushed.
20. Test the changes locally to confirm their working and make a pull request by clicking on the Open Pull Request button, located at the right-side of the recently pushed branch name.
21. Enter an appropriate pull request title and describe the changes made in detail with Markdown-compliant syntax. If the pull request is draft, do reflect the same on the pull request title using a WIP tag to keep the pull request from getting merged before completion.

forkcode.md

Making contributions to the repository

The key goals of this effort of maintaining websites include:

1. Consolidating all key Fedora websites onto one uniform scheme - concerning interaction and technology
2. Maintaining and exhibiting content on the websites that cannot be categorized under any particular sub-project
3. Generally making the sites as fun and exciting as the projects they represent

To better achieve these goals, as well as to benefit the community, the work of this project will involve third-party site maintainers, wherever possible. The direct work of this project is limited to the formal Get Fedora site.

Tasks on specific sections of the sites will be coordinated by the appropriate projects. A great deal of coordination will be necessary with the Fedora Infrastructure Team, Fedora Documentation Project, and the Fedora Marketing Project.

getstart.md

Contributing to Fedora Websites

Thank you for considering to contribute to the Fedora Websites repository. This repository houses a collection of websites that act as a gateway for the world to know who we are as a community and help us send out updates about new releases, events and community news. Following in the list of websites, arranged in no specific order, that are maintained within this repository.

1. Alternative Downloads (https://alt.fedoraproject.org)
2. Fedora ARM Downloads (https://arm.fedoraproject.org)
3. Fedora Budget (https://budget.fedoraproject.org)
4. Fedora Community (https://fedoracommunity.org)
5. Fedora Labs Downloads (https://labs.fedoraproject.org)
6. Fedora Spins Downloads (https://spins.fedoraproject.org)
7. Fedora Start (https://start.fedoraproject.org)
8. Fedora Mirrors (https://mirrors.fedoraproject.org)
9. Flock to Fedora (https://flocktofedora.org)
10. Fedora People (https://fedorapeople.org)

The repository is located on Pagure, our own in-house source code management service at https://pagure.io/fedora-websites/. In order to understand what each website does, visiting the aforementioned links is suggested.

testloca.md

Testing changes locally

One would want to test changes made locally before pushing commits to minimize the delay between review and changes, to prevent breaking changes from being merged into the primary branch of the repository, and avoid tainting of commit history which can happen as a consequence of correcting the previously mistaken changes.

In order to test changes locally, a working Podman installation is required. A significant part of this documentation is a derivative of the documentation about adding your code to the repository, so it is strongly recommended reading that first. Make sure that the Dockerfile is available at the root directory of the repository.

1. Install Podman
   1. On Fedora/CentOS/RHEL/OpenSUSE by executing the following command on a terminal.

      sudo dnf install podman
      

   2. On Debian/Ubuntu/Linux Mint/KDE Neon/Pop!_OS by executing the following command on a terminal.

      sudo apt install podman
      

   3. On Arch/Antergos/Manjaro/Endeavor by executing the following command on a terminal.

      sudo pacman -S podman
      

Go through the following steps in order to test your changes locally.

1. Open a terminal from within the location where the repository is cloned.
2. Execute the following command to build an image from the reference Dockerfile.

   podman build . -f Dockerfile -t fedora-websites:latest
   

3. Execute the following command to start the container and passthrough the pseudo-TTY to the terminal.

   podman run -ti \
     -p 6969:5000/tcp \
     -v $(pwd):/opt/oldrepo:z \
     fedora-websites:latest
   

   Let us understand in detail what the above command does.
   1. run starts up a new container of the said image (here, fedora-websites:latest)
   2. -p maps a designated port on host device to a designated port on container (here, port 5000 of container is mapped with port 6969 of host device)
   3. -v mounts a designated volume/directory on host device to designated volume/directory on container (here, <repository-absolute-location> is the aboslute location of the directory on the host device where the repository is cloned, which is mapped with /opt/oldrepo directory from inside the container with suitable access privileges)
   4. -ti passes through the pseudo-TTY to the terminal - allowing the user to interact with the container directly.
4. Now from within the pseudo-TTY of the container, navigate into the /opt/oldrepo directory where the repository files would be mounted and then navigate into a directory of the website that you want to test the preview of (say for instance, start.fedoraproject.org) by executing the following command from within the pseudo-TTY of the container.

   cd start.fedoraproject.org
   

5. Launch a test instance in the foreground by executing the following command from within the pseudo-TTY of the container and check the changes made in an internet browser of choice.

   make en testfg
   

   Let us understand in detail what the above command does.
   1. make runs directives from Makefile and other dependent Python modules to build and start a test server on a designated port in the container. This port is mapped with a designated port on the host device so using an internet browser of choice, one can navigate to http://localhost:<mapped-host-port> (which is 6969 in this case) to check the changes.
   2. en stands for English. All the websites housed inside the repository are translation-ready, thanks to our localization team and stating this explicitly asks for building with the English translations included. Using an internet browser of choice, navigate to http://localhost:<mapped-host-port>/en (which is 6969 in this case) to check the changes specific to the English language.
   3. testfg runs the test instance in the foreground, which can be exited out of by raising a keyboard interrupt (i.e., pressing Ctrl+C key combination).
6. Exit out of the test instance by raising a keyboard interrupt (i.e., pressing Ctrl+C key combination) and execute the following command to clean the instance and prevent caching problems.

   make veryclean
   

7. It is strongly recommended to keep aside the fedora-websites:latest image until any changes are made to the Dockerfile as the same image can be repurposed for testing - effectively letting the test start from step #3 from the next time onwards.
8. It is also suggested to study the flags, options and directives available in the Makefile file inside each website directory to better understand how each website can be built and tested locally.