• Overview
• Steps
  • Create repository
  • Publish
  • Clone repository
  • Edit proposal
  • Edit project configuration
  • Commit and push
  • Review and refine

Overview

Before you start working in earnest on your personal Android project—even on the high-level design—you need to write a proposal that is accepted by the instructors. This is a multi-step process: You must submit a first draft, followed by one or more rounds of instructor feedback with (if directed by the instructors) subsequent revision by you. (Sometimes, the topic itself is not suitable; when this is the case, starting a new proposal may be the best way to proceed.)

In past cohorts, each student has written and refined a proposal in one repository, and then created an entirely new repository for the project, copying the text of the proposal to the new repository as the basis for the the project overview component of the project documentation. However, we have streamlining this process slightly. You will still create a repository (by accepting a GitHub Classroom assignment), in which you write and refine your proposal—but this repository also contains a structure suitable for an Android project, so you will continue to use it as you develop your Android app.

Before starting on your proposal, as you consider what you would like to do for your personal Android project, please keep in mind the expected implementation elements, as well as the features that are specifically declared out-of-scope.

Follow the steps below to create the repository, publish it with GitHub Pages, and edit its content to write the first draft of your proposal.

Important

• Please notice that all of the screen shots in the instructions are for a repository named personal-android-project-nick-bennett, but your repository will have your GitHub user name at the end, in place of nick-bennett. Similarly, the app name used in the screen shots is “Fair Play”, but you will use your intended app name.

• Please read the instructions below carefully, before starting your proposal. There are several steps to complete; none are very difficult, but there are many details to pay attention to.

Steps

Create repository

The repository for your personal Android project isn’t one you will create directly on GitHub, or locally in Git. Instead, you will create it indirectly, by accepting a GitHub Classroom assignment.

1. Use the link provided by your instructor and follow the prompts to accept the personal-android-project assignment. (If this is your first GitHub Classroom assignment for this cohort, you will need to identify yourself in the class roster before you can accept the assignment.)

   

   

   

2. Click the displayed repository link to navigate to your newly created repository in GitHub.

3. Click the Issues tab, and note that 6 issues have been created. Each of these issues corresponds to one of the categories below, and each has checkboxes to help you keep track of what has been completed. We recommend that you keep these issues open in one browser tab, while you have the instructions below in another tab—even while you use additional tabs to modify the repository settings, review the GitHub Pages site, etc.

Publish

1. In the row of tab buttons that appears just below the repository name near the top of the window, click Settings (at or near the right end of the row).

   

2. In the Settings page for this repository, scroll down in the left sidebar and click the Pages item, near the bottom of the list.

   

3. Making the following selections in the Source sub-section:

   • Branch: main
   • /docs

   

4. Click the Save button in the Source sub-section. After this, a URL will appear at the top of the GitHub Pages section (you’ll need to scroll down again to see it), after the text “Your is ready to be published at”, or “Your site is published at”; this is the URL of the GitHub Pages site created from your repository. Note that it can take a few minutes for the site to be available—especially when it is first published.

   

Clone repository

1. In the row of tab buttons just below the repository name, click Code (at or near the left end of the row).

2. Click the large green Code button that contains a pull-down control indicator (a downward-pointing triangle).

   

3. Select the SSH option (if it is not already selected) in the Clone pull-down dialog.

4. Click the clipboard icon to the right of the URL (which should begin with git@github.com:) to copy the URL to the clipboard.

5. In IntelliJ, click the Get from VCS button (in the Welcome to IntelliJ IDEA window, shown below on the left) or select the File/New/Project from Version Control menu option (In the IntelliJ workspace, shown below on the right).

   

6. Paste the URL you copied in step 4 to the URL field of the Get from Version Control window.

7. Adjust the contents of the Directory field (if necessary), so that the it ends with bootcamp\projects\ or bootcamp/projects/, followed by the repository name personal-android-project-GitHub-user-name (this last element is essential: please do not create a project directly in the bootcamp\projects directory).

8. Click the Clone button.

   After the repository is cloned, IntelliJ will import it automatically. This process can take anywhere from 20 seconds to a few minutes. While the import is in-progress, it’s recommended that you don’t modify the project content. Instead, wait until all of the indexing/building/downloading messages have stopped displaying at the bottom of the workspace, before proceeding with the next steps.

Edit proposal

1. Use the pull-down at the top of the Project tool window to change the current view to “Project”.

2. In the Project tool window (along the upper left side of the workspace, select and open the README.md file.

3. Edit README.md:

   1. On the first line (the heading), after the hash mark (aka pound sign, or #) and the space that follows it, replace the text that’s there with the name of the app you propose to develop. (This doesn’t have to be the final name.)

   2. Replace the paragraph below the heading with a paragraph summarizing your proposed app.

4. In the Project tool window (along the upper left side of the workspace, select and open the docs/_config.yml file.

   

5. Edit _config.yml, replacing the default values of the title, description, and author.name properties (in the screen capture above, these properties are in lines 11, 12, and 14) with your proposed project title, a one-sentence description of the project, and your name (respectively). Please preserve the formatting of this file (including any indentation), the quotes around the values of the properties, and the space between the colon character and the start of the quoted property value in each of the properties you edit.

6. Select and open the docs/index.md file. By default, IntelliJ displays Markdown files in a split-pane view, with the editable text on the left-hand side, and the preview rendering on the right-hand side; you can change the selected view by clicking the desired icon on the upper-right, just above the document being edited. (If you hover the mouse over these icons, a tooltip will be displayed. In this case, those tooltips are “Show Editor Only”, “Show Editor and Preview”, and “Show Preview Only”.

   

7. Edit index.md, replacing the placeholder text as appropriate for your proposal.

   Every section in the document starts with a level-2 heading (e.g. ## Summary). For this first draft, keep all of the section headings as they are. However, you must replace the instructions/sample text below each heading, by providing the relevant information of your proposal, as directed in the instructions for each section. Please read the text of each of those sections carefully: in several cases, the instructions direct you to use specific Markdown constructs to format the content.

   For this first draft, if you’re not able to provide content for any given section, don’t delete that section; instead, leave the heading as-is, and type “TBD” as the text for the section. However, do your best to complete at least the Summary, Intended users, and Functionality sections—and as much of the remaining content as possible.

   If you would like to view examples of completed proposals, please see the following:

   • Fair Play
   • Endangered Species Tracker (EST)

Edit project configuration

Important: The screenshots below are based on an example for an app to be called “Fair Play”; this is just an example: You should use a suitable name for the app you are proposing to develop.

1. Use the pull-down at the top of the Project tool window to change the current view to “Android”¹.

   

2. Expand the app tree to show, and then select, app/java/edu.cnm.deepdive.appstarter.

   

   The selected package, edu.cnm.deepdive.appstarter is the main package of your app. Next, you’ll rename the last part of this to match your intended app name more closely.

3. With the main package selected in the Android view, select the Refactor/Rename menu command.

   

4. In the Warning alert dialog that appears, press the In Whole Project button.

   

5. In the Rename dialog, replace “appstarter” in the first field with a variant of your intended app name that follows these rules:

   • No uppercase letters allowed.
   • No spaces allowed.
   • No punctuation of any type allowed.
   • Digits are allowed, but the first character must be a letter.

   In the example below, my app name “Fair Play” is written as “fairplay”, to follow the rules above.

   

6. Click the Refactor button.

7. If a refactoring preview appears in the lower-left of the screen, click the Do Refactor button that appears at the bottom.

   

8. Verify that all of the packages in the app/java sub-tree of the Android view now begin with edu.cnm.deepdive., followed by the app name you typed in step 5.

   

9. In the Android view of the Project tool window, expand the item you just renamed to show, and then select, AppStarterApplication.

   

10. With AppStarterApplication selected in the Android view, select the Refactor/Rename menu command.

11. In the edit field, change the “AppStarter” part of “AppStarterApplication” to the name of your app in UpperCamelCase (that is, starting with an uppercase character, and—if the name includes multiple words—joining the words together, with each word starting with an uppercase character). Be sure to keep the “Application” part at the end.

    In the example below, the app name “Fair Play” is included as “FairPlay” in the class name “FairPlayApplication”, to follow the rules of UpperCamelCase.

    

12. Click the Refactor button.

13. In the Android view of the Project tool window, expand the Gradle scripts sub-tree and open the second build.gradle file that appears (the one followed by “Module: personal-android-project.app” in parentheses).

    

14. Edit the value of the applicationId property (line 10 in the screen capture above), so that it matches your new main package name—that is, with edu.cnm.deepdive. followed by the app name variant you typed in step 5. Important: Make sure that this match is exact, including the lowercase letter casing. (For now, disregard the “Gradle files have changed” notification that appears at the top of the window after you start typing.)

    

15. From the Gradle scripts sub-tree of the Android view, open the gradle.properties file.

    

16. Edit the value of the appName property—that is, the text after the equals sign on line 23—replacing App Starter with your intended app name. This time, the rules are a bit more relaxed: the name can contain mixed-case letters, digits, and spaces.

    

17. From the Gradle scripts sub-tree of the Android view, open the settings.gradle file.

    

18. Edit the value of the rootProject.name property—that is, the text between the double quotation marks on line 2. Between the double quotes, replace personal-android-project with the lower-spinal-case form (that is, all lowercase, with dashes between the words) of your intended app name.

    

19. From the Build menu at the top of the window (in Windows or Linux Ubuntu) or the top of the screen (in OS X), select the Rebuild Project option.

    

20. Verify that you now see the lower-spinal-case form of your app name in the window title bar (on Windows or Ubuntu). If you still see “personal-android-project”, verify that you completed all of the above steps: if you missed any of them, return to the that point in the instructions, and complete all of the steps from there.

    

Commit and push

1. Select the Git/Commit command (also available via the Ctrl-K keyboard shortcut on Windows & Linux, or Cmd-K on OS X) to display the modal (left image) or non-modal (right image) commit dialog. (You can set your modal/non-modal preference for this dialog in the Version Control/Commit settings available via the File/Settings menu command.)

   

2. Click on the checkboxes as necessary to make sure that all files that appear in the changelist are selected.

3. Type a commit message in the designated field. (For now, “Initial commit” is just fine.)

4. Select the Commit & Push command (in the modal dialog, this is available by clicking the pull-down control next to the Commit button) to commit your changes to the local repository, and display the Push Commits window automatically.

   

Review and refine

1. Review the GitHub Pages site created from your repository, using the URL referenced in step 4 of “Publish”, above. Pay attention not only to content, but formatting as well.

2. Repeat the “Edit proposal” and “Commit and push” sections as necessary.

1. If you don’t see “Android” as an option, it’s possible that you didn’t tell IntelliJ to import the Gradle project found in the repository. This can be fixed by closing the project (use the File/Close Project menu command), then deleting the .idea directory from the project directory (using File Explorer in Windows, Finder in OS X, or File Manager in Ubuntu), re-opening the project in IntelliJ, and confirming the Gradle import in the pop-up that appears in the lower-right corner of the workspace. If you are unable to resolve the problem this way, please contact an instructor for assistance. ↩